OAS 3 This page applies to OpenAPI 3 – the latest version of the OpenAPI Specification. If you use OpenAPI 2 (fka Swagger), visit OpenAPI 2 pages.

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

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