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:

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

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

1
enum:
2
  - asc
3
  - 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:

1
parameters:
2
  - in: query
3
    name: sort
4
    schema:
5
      type: string
6
      enum: [asc, desc]
7
    description: >
8
      Sort order:
9
       * `asc` - Ascending, from A to Z
10
       * `desc` - Descending, from Z to A

Nullable enums

A nullable enum can be defined as follows:

1
type: string
2
nullable: true  # <---
3
enum:
4
  - asc
5
  - desc
6
  - null        # <--- without quotes, i.e. null not "null"

Note 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.

1
paths:
2
  /products:
3
    get:
4
      parameters:
5
        - in: query
6
          name: color
7
          required: true
8
          schema:
9
            $ref: "#/components/schemas/Color"
10
      responses:
11
        "200":
12
          description: OK
13
components:
14
  schemas:
15
    Color:
16
      type: string
17
      enum:
18
        - black
19
        - white
20
        - red
21
        - green
22
        - blue

Did not find what you were looking for? Ask the community
Found a mistake? Let us know