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.

score 16 · Answer 1 · answered Aug 27 '15 at 18:15

16

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.

answered Aug 27 '15 at 18:15

Ron

14,160
3
52
39

2

No, but it looks like in 3.0 it will be possible. – Ron Apr 22 '16 at 12:57
@Ron Looking forward to it. Seems really useful. – Sanket Berde Sep 14 '16 at 19:29
1

I'm having the same exact issue. Is there a resolution for this? I'd love to be able to reuse enum definitions across parameters. – Detuned Apr 12 '17 at 21:01
1

The behavior changes in the next version of the spec. – Ron Apr 12 '17 at 21:30

score 12 · Accepted Answer · answered Jan 30 '18 at 17:38

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

Swagger: Reusing an enum definition as query parameter

2 Answers2

Linked