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
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.