OAS 3 本指南适用于 OpenAPI 3.0。如果您使用 OpenAPI 2.0，请查看我们的 OpenAPI 2.0 指南。

枚举

您可以使用 enum 关键字指定请求参数或模型属性的可能值。例如，GET /items?sort=[asc|desc] 中的 sort 参数可以描述为

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

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

          enum:
            - asc
            - desc

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

      parameters:
        - in: query
          name: sort
          schema:
            type: string
            enum: [asc, desc]
          description: >
            Sort order:
             * `asc` - Ascending, from A to Z
             * `desc` - Descending, from Z to A

可空枚举

可空枚举可以定义如下

type: string
nullable: true  # <---
enum:
  - asc
  - desc
  - null        # <--- without quotes, i.e. null not "null"

请注意，null 必须明确包含在 enum 值列表中。仅使用 nullable: true 在这里是不够的。

可重用枚举

在 OpenAPI 3.0 中，操作参数和数据模型都使用 schema，这使得数据类型的重用变得容易。您可以在全局 components 部分定义可重用枚举，并在其他地方通过 $ref 对其进行引用。

paths:
  /products:
    get:
      parameters:
      - in: query
        name: color
        required: true
        schema:
          $ref: '#/components/schemas/Color'
      responses:
        '200':
          description: OK
components:
  schemas:
    Color:
      type: string
      enum:
        - black
        - white
        - red
        - green
        - blue

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