Swagger: Reusing an enum definition as query parameter

Question

I would like to use an enum defined in definitions as part of my parameter definitions in a query string.

I'm defining the Swagger Enum in the definitions part of my Swagger 2.0 spec file.

OperationType:
  type: string
  enum:
  - registration
  - renewal

I can create references to it in other definitions:

Operation:
  type: object
  properties:
    name:
      type: string
    type:
      $ref: '#/definitions/OperationType'

I can use the schema tag to make a reference to it when the parameter is in: body, but not when it's in: query

    - name: operation
      in: body
      description: description
      schema:
        $ref: '#/definitions/OperationType'

I tried dropping schema: and making a reference in enum: instead, but can't get it to work.

Answer 1

For Swagger 2.0, we've limited the ability to use model definitions for anything but body parameters. The definitions section is used to define schema, which can also be used to define non-objects. However, those definitions can only be accessed where the schema keyword is used. As initially stated, schema not accessible for non-body parameters, and as such, cannot be used by query or path parameters, thus limiting the ability to reuse those definitions.

There's an open feature request asking for it to be handled in a future version of the spec.

Answer 2

This is possible in OpenAPI 3.0. All parameters now use a schema, and, by extension, can $ref the schemas.

openapi: 3.0.0
...
paths:
  /something:
    get:
      parameters:
        - in: query
          name: action
          schema:
            $ref: '#/components/schemas/OperationType'
      ...

components:
  schemas:
    OperationType:
      type: string
      enum:
        - registration
        - renewal