枚举

您可以使用 enum 关键字来指定请求参数或模型属性的可能值。例如，在

1
GET /items?sort=[asc|desc]

中的 sort 参数可以描述为

1
paths:
2
  /items:
3
    get:
4
      parameters:
5
        - in: query
6
          name: sort
7
          description: Sort order
8
          type: string
9
          enum: [asc, desc]

在 YAML 中，您也可以每行指定一个枚举值

1
enum:
2
  - asc
3
  - desc

枚举中的所有值都必须符合指定的类型。如果您需要为枚举项指定描述，可以在参数或属性的 description 中执行此操作

1
type: string
2
enum:
3
  - asc
4
  - desc
5
description: >
6
  Sort order:
7
   * asc - Ascending, from A to Z.
8
   * desc - Descending, from Z to A.

可重用枚举

OpenAPI 3.0 中支持可重用的枚举定义。

虽然 Swagger 2.0 没有内置的对可重用枚举的支持，但可以在 YAML 中使用 YAML 锚点定义它们 – 前提是您的工具支持它们。锚点是 YAML 的一个方便功能，您可以用 &anchor-name 标记一个键，然后在下方使用 *anchor-name 来引用该键的值。这使您可以轻松地在 YAML 文件中复制内容。

注意：必须在使用之前定义锚点（&）。

1
definitions:
2
  Colors:
3
    type: string
4
    enum: &COLORS
5
      - black
6
      - white
7
      - red
8
      - green
9
      - blue
10
    # OR:
11
    # enum: &COLORS [black, white, red, green, blue]
12

13
paths:
14
  /products:
15
    get:
16
      parameters:
17
        - in: query
18
          name: color
19
          required: true
20
          type: string
21
          enum: *COLORS
22
      responses:
23
        200:
24
          description: OK

如果您的工具的 YAML 解析器支持 YAML 合并键（<<），则可以使用此技巧来引用类型和枚举值。

1
definitions:
2
  Colors: &COLORS
3
    type: string
4
    enum: [black, white, red, green, blue]
5
paths:
6
  /products:
7
    get:
8
      parameters:
9
        - in: query
10
          name: color
11
          required: true
12
          <<: *COLORS
13
      responses:
14
        200:
15
          description: OK

没有找到您要找的内容？咨询社区
发现错误？请告知我们