Swagger yaml定义Restful API那些事（持续更新）

一、复杂模型

1、Value是一个Map<String, Map<String, String>>结构

嵌套Map的数据结构，如下示意

"translations": {
  "zh-CN": {
    "hello.world": "你好,世界"
    "hello.earth": "你好,地球"
    "hello.mars": "你好,火星"
  },
  "en-US": {
    "hello.world": "Hello World"
    "hello.earth": "hello earth"
    "hello.mars": "hello mars"
  }
}

yaml定义如下：

BaseModel:
  type: object
  discriminator: name
  properties:
    translations:
        $ref: '#/definitions/Translate'
        
Translate:
  additionalProperties:
    $ref: '#/definitions/TranslateItem'

TranslateItem:
  additionalProperties:
    type: string

解释：

additionalProperties用于表示Map里面Value值的类型。

二、枚举相关

1、swagger yaml定义字符串的有效值范围，可以如下animal方式

2、如果定义一个属性的值就是一个枚举类型，可以用beasts方式

definitions:
  MyLoves:
    type: object
    properties:
      animal:
        type: string
        enum:
          - "dog"
          - "cat"
      beasts:
        $ref: '#/definitions/Beasts'

  Beasts:
    enum:
      - "donkey"
      - "pig"
    type: string
    x-ms-enum:
      name: Beasts
      modelAsString: true