枚举

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

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

可以描述为

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

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