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:

1
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
          type: string
9
          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
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.

Reusable Enums

Reusable enum definitions are supported in OpenAPI 3.0.

While Swagger 2.0 does not have built-in support for reusable enums, it is possible to define them in YAML using YAML anchors – provided that your tool supports them. Anchors are a handy feature of YAML where you can mark a key with &anchor-name and then further down use *anchor-name to reference that key’s value. This lets you easily duplicate the content across a YAML file.

Note: An anchor (&) must be defined before it is used.

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

If your tool’s YAML parser supports YAML merge keys (<<), you can use this trick to reference both the type and the enum values.

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

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