I'm struggling with the syntax of swagger to describe a response type. What I'm trying to model is a hash map with dynamic keys and values. This is needed to allow a localization. The languages may vary, but english should always be provided.
The response would look like this in JSON:
{
id: "1234",
name: {
en: "english text",
de: "Deutscher Text"
}
}
My first try was looking like that, but I have no idea how to write the part for the name. AdditionalProperties seems to be a key, but I can't wrap my head around it. Also the requirement for english text is a mystery to me in this syntax and the example also does not seem to work as expected. It generates an empty $folded: in the UI.
delayReason:
type: object
properties:
id:
type: string
description: Identifier for a delay reason.
name:
type: object
additionalProperties:
type: string
required: [id, name]
example:
id: 123
name:
en: english text
de: Deutscher Text
But this produces:
There is also no clue in this that the result will have a language code as a key and the text as the value of the hash map.
Your usage of additionalProperties
is correct and your model is correct.
In Swagger/OpenAPI, hashmap keys are assumed to be strings, so the key type is not defined explicitly. additionalProperties
define the type of hashmap values. So, this schema
type: object
additionalProperties:
type: string
defines a string-to-string map such as:
{
"en": "English text",
"de": "Deutscher Text"
}
If you needed a string-to-integer map such as:
{
"en": 5,
"de": 3
}
you would define additionalProperties
as having value type integer
:
type: object
additionalProperties:
type: integer
To define en
as a required key in the hashmap:
type: object
properties:
en:
type: string
required: [en]
additionalProperties:
type: string
definitions:
delayReason:
type: object
properties:
id:
type: string
description: Identifier for a delay reason.
name:
type: object
description: A hashmap with language code as a key and the text as the value.
properties:
en:
type: string
description: English text of a delay reason.
required: [en]
additionalProperties:
type: string
required: [id, name]
example:
id: '123' # Note the quotes to force the value as a string
name:
en: English text
de: Deutscher Text
There is also no clue in this that the result will have a language code as a key and the text as the value of the hash map.
Things like that can be documented verbally in the description
.
the example also does not seem to work as expected. It generates an empty $folded: in the UI.
Not sure what the problem was with your original spec, but the spec above is valid and looks fine in the Swagger Editor.
It seems you are running into at least three separate bugs and/or limitations:
Neither Swagger-Editor nor Swagger-UI provide any indication in the documentation format to show that additionalProperties
are allowed in your object schema. So even where you've used additionalProperties
correctly, and it's recognized by the Swagger parser, these documentation formats won't show it. You need to add this detail to your schema description
, so users understand that they can include additional string properties.
Note: You probably also expect the additional property names to follow a convention, e.g. a two-letter language code. While full JSON Schema lets you specify this with patternProperties
, unfortunately that's not supported in Swagger's schema object. So again, you should specify that in your schema description.
The Swagger-Editor format sometimes shows this odd "folded:" property. I saw it this morning, now strangely I cannot reproduce it. It might have been hotfixed today. But regardless, it's certainly a bug, and specific to Swagger-Editor. It should not affect your downstream code generation, nor the standard Swagger-UI that presents your API documentation to client developers at runtime. (Though the documentation pane in Swagger-Editor looks similar to Swagger-UI, it is a separate implementation.)
There are some subtle but significant limitations to the use of additionalProperties
in Swagger. While Helen's example doesn't show any visible errors, in fact the Swagger parser will fail to process this schema correctly; it will ignore either your explicitly declared en
property, or will ignore additionalProperties
!
This last issue comes down to a design flaw in Swagger-Model, one of the core components used throughout the Swagger Java stack (including Swagger-Codegen). Schemas defined in certain contexts can work with a combination of properties
and additionalProperties
. But schemas defined in other contexts cannot.
We've documented this in detail here.
The good news: with a small tweak, we can make Helen's example work correctly. We just need to extract the nested object schema into its own top-level definition. I'll call it LocalizedName
:
definitions:
delayReason:
type: object
properties:
id:
type: string
description: Identifier for a delay reason.
name:
$ref: "#/definitions/LocalizedName"
required: [id, name]
example:
id: '123' # Note the quotes to force the value as a string
name:
en: English text
de: Deutscher Text
LocalizedName:
type: object
description: A hashmap with language code as a key and the text as the value.
properties:
en:
type: string
description: English text of a delay reason.
required: [en]
additionalProperties:
type: string
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With