Swagger: take one or more values from enum

Question

I am working on a swagger file, where a query parameter can take none, or n values. How can I write this in Swagger Yaml?

The url I give: /sort=field1,field2

The parameter declared in swagger file

- name: sort
  in: query
  schema:
    type: string
    enum: [field1,field2,field3]
  allowEmptyValue: true
  required: false
  description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)

Have a nice day/night.

Answer 1

A query parameter containing a comma-separated list of values is defined as an array. If the values are predefined, then it's an array of enum.

By default, an array may have any number of items, which matches your "none or more" requirement. If needed, you can restrict the number of items using minLength and maxLength, and optionally enforce uniqueItems: true.

OpenAPI 2.0

The parameter definition would look as follows. collectionFormat: csv indicates that the values are comma-separated, but this is the default format so it can be omitted.

      parameters:
        - name: sort
          in: query
          type: array  # <-----
          items:
            type: string
            enum: [field1, field2, field3]
          collectionFormat: csv  # <-----
          required: false
          description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)

OpenAPI 3.0

collectionFormat: csv from OpenAPI 2.0 has been replaced with style: form + explode: false. style: form is the default style for query parameters, so it can be omitted.

      parameters:
        - name: sort
          in: query
          schema:
            type: array  # <-----
            items:
              type: string
              enum: [field1, field2, field3]
          required: false
          description: Sort the results by attributes. (See http://jsonapi.org/format/1.1/#fetching-sorting)
          explode: false  # <-----

I think there's no need for allowEmptyValue, because an empty array will be effectively an empty value in this scenario. Moreover, allowEmptyValue is not recommended for use since OpenAPI 3.0.2 "as it will be removed in a future version."