OAS 2 此页面适用于 OpenAPI 规范版本 2（以前称为 Swagger）。若要了解最新版本，请访问 OpenAPI 3 页面.

枚举

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

GET /items?sort=[asc|desc]

可以描述为

paths:
  /items:
    get:
      parameters:
        - in: query
          name: sort
          description: Sort order
          type: string
          enum: [asc, desc]

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

          enum:
            - asc
            - desc

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

          type: string
          enum:
            - asc
            - desc
          description: >
            Sort order:
             * asc - Ascending, from A to Z.
             * desc - Descending, from Z to A.

可重复使用的枚举

可重复使用的枚举定义在 OpenAPI 3.0 中受支持。

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

注意： 必须在使用锚点 (&) 之前定义它。

definitions:
  Colors:
    type: string
    enum: &COLORS
      - black
      - white
      - red
      - green
      - blue
    # OR:
    # enum: &COLORS [black, white, red, green, blue]

paths:
  /products:
    get:
      parameters:
        - in: query
          name: color
          required: true
          type: string
          enum: *COLORS
      responses:
        200:
          description: OK

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

definitions:
  Colors: &COLORS
    type: string
    enum: [black, white, red, green, blue]
paths:
  /products:
    get:
      parameters:
        - in: query
          name: color
          required: true
          <<: *COLORS
      responses:
        200:
          description: OK

  

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