Enums

You can use the enum keyword to specify possible values of a request parameter or a model property. For example, the sort parameter in GET /items?sort=[asc|desc] can be described as:

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

In YAML, you can also specify one enum value per line:

          enum:
            - asc
            - desc

All values in an enum must adhere to the specified type. If you need to specify descriptions for enum items, you can do this in the description of the parameter or property:

      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

Nullable enums

A nullable enum can be defined as follows:

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

ote that null must be explicitly included in the list of enum values. Using nullable: true alone is not enough here.

Reusable enums

In OpenAPI 3.0, both operation parameters and data models use a schema, making it easy to reuse the data types. You can define reusable enums in the global components section and reference them via $ref elsewhere.

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