app开发定制Swagger yaml定义Restful API那些事（持续更新）

一、复杂模型

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

嵌套Mapapp开发定制的数据结构，如下示意

"translations": {  "zh-CN": {    "hello.world": "你好,世界"    "hello.earth": "你好,地球"    "hello.mars": "你好,火星"  },  "en-US": {    "hello.world": "Hello World"    "hello.earth": "hello earth"    "hello.mars": "hello mars"  }}
1
2
3
4
5
6
7
8
9
10
11
12

yaml定义如下：

BaseModel:  type: object  discriminator: name  properties:    translations:        $ref: '#/definitions/Translate'        Translate:  additionalProperties:    $ref: '#/definitions/TranslateItem'TranslateItem:  additionalProperties:    type: string
1
2
3
4
5
6
7
8
9
10
11
12
13
14

解释：

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

二、枚举相关

1、 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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20