Swagger: take one or more values from enum

by

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 minItems and maxItems, 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.x

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.”

More Related Contents:

  1. How to return an array of objects in SwaggerHub?
  2. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  3. Swagger schema properties ignored when using $ref – why?
  4. Swagger 2.0: Multiple Path objects with different paths but same request and response
  5. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  6. Swagger: wildcard path parameters
  7. Schema object without a type attribute in Swagger 2.0
  8. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  9. How to specify if a field is optional or required in OpenAPI/Swagger?
  10. Swagger/OpenAPI mock server
  11. How to document dynamic query parameter names in OpenAPI (Swagger)?
  12. How can I represent ‘Authorization: Bearer ‘ in a Swagger Spec (swagger.json)
  13. How to define a property that can be string or null in OpenAPI (Swagger)?
  14. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  15. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  16. Swagger complex response model with dynamic key value hash maps
  17. How to define an optional parameter in path using swagger
  18. Swagger: “equivalent path already exists” despite different parameters
  19. Re-using model with different required properties
  20. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  21. How not to copy-paste 3 generic error responses in almost all paths?
  22. How to define global parameters in OpenAPI?
  23. Swagger Inheritance and Composition
  24. OpenAPI: what schema to accept any (complex) JSON value
  25. Swagger: map of
  26. Use object type query param in swagger documentation
  27. Freeform subobject in json-schema
  28. How to configure Spring Security to allow Swagger URL to be accessed without authentication
  29. How to format Swagger 2.0 text descriptions?
  30. How do I combine multiple OpenAPI 3 specification files together?

Leave a Comment