Swagger 2: use enum reference in query parameter of array type

Question

Can not get how to use reference of string type with enum values in array parameter. I can make reference in items key and it is working, but Swagger produce error: Not a valid parameter definition

Web UI generates interface, but it have textarea instead of multiselect box I expected.

What is the proper way to do it?

My code:

    swagger: '2.0':
    paths:
      /test:
        get:
          parameters:
          - in: origin
            name: status
            description: Origin
            required: false
            schema:
              type: array
              items:
                $ref: '#/definitions/Origin'
            collectionFormat: pipes'
    definitions:
      Origin:
        type: string
        description: Campaign origin
        enum:
          - one
          - two
    externalDocs:
      description: Find out more about Swagger
      url: http://swagger.io
    host: virtserver.swaggerhub.com
    basePath: /

Community · Accepted Answer · 2017-05-23 12:01:52Z

2

Array parameters with items containing $ref are not supported in OpenAPI/Swagger 2.0. But it looks like this will be possible in the next version, 3.0. For now there are a couple of workarounds, see below.

Your spec also has some other issues:

in: origin is not valid. The in keyword specifies the parameter location (path, query, header, etc.) and only accepts certain values as per the OpenAPI/Swagger spec. I guess you meant in: query or in: header.
Typos (or copy-paste errors?): swagger: '2.0': has an extra : at the end and collectionFormat: pipes' has an extra ' at the end.

One solution for having an array parameter containing enum values is to define the enum inline:

      parameters:
        - in: query
          name: status
          description: Origin
          required: false
          type: array
          collectionFormat: pipes
          items:
            type: string
            enum:
              - one
              - two

Another solution (found here) is to use YAML anchors to reference the enum. This is a 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.

definitions:
  Origin:
    type: string
    description: Campaign origin
    enum: &origin
      - one
      - two

paths:
  /test:
    get:
      parameters:
        - in: query
          name: status
          description: Origin
          required: false
          type: array
          collectionFormat: pipes
          items:
            type: string
            enum: *origin

edited May 23, 2017 at 12:01

CommunityBot

11 silver badge

answered Jan 13, 2017 at 20:57

Helen

99.8k18 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Nainesh Patel Over a year ago

I am having the same issue. Swagger.json generated by project is returning same error since items has $ref. Can you help me how to remove $ref and add enum in c#? Project is net core 3.1.

user3712978 · Accepted Answer · 2019-10-29 16:07:35Z

-1

One option is to define a parameter and make a reference to that: (I had an issue with using reference ($ref:) within a query definition)

paths:
  /path:
    get:
      operationId: controllers.controller
      parameters:
        **- $ref: '#/parameters/SPEC'**


parameters:
  SPEC:

answered Oct 29, 2019 at 16:07

user3712978

1672 silver badges6 bronze badges

Collectives™ on Stack Overflow

Swagger 2: use enum reference in query parameter of array type

2 Answers 2

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related