Welcome to OGeek Q&A Community for programmer and developer-Open, Learning and Share
Welcome To Ask or Share your Answers For Others

Categories

0 votes
1.2k views
in Technique[技术] by (71.8m points)

hashmap - Swagger complex response model with dynamic key value hash maps

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: swagger editor result

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.

See Question&Answers more detail:os

与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
Welcome To Ask or Share your Answers For Others

1 Reply

0 votes
by (71.8m points)

Your usage of additionalProperties is correct and your model is correct.

additionalProperties

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

Required key in a hashmap

To define en as a required key in the hashmap:

type: object
properties:
  en:
    type: string
required: [en]
additionalProperties: 
  type: string

Complete example

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.

Model schema in Swagger Editor


与恶龙缠斗过久,自身亦成为恶龙;凝视深渊过久,深渊将回以凝视…
OGeek|极客中国-欢迎来到极客的世界,一个免费开放的程序员编程交流平台!开放,进步,分享!让技术改变生活,让极客改变未来! Welcome to OGeek Q&A Community for programmer and developer-Open, Learning and Share
Click Here to Ask a Question

...