How to define mutually exclusive query parameters in Swagger (OpenAPI)?

by

Mutually exclusive parameters are possible (sort of) in OpenAPI 3.x:

  • Define the mutually exclusive parameters as object properties, and use oneOf or maxProperties to limit the object to just 1 property.
  • Use the parameter serialization method style: form and explode: true, so that the object is serialized as ?propName=value.

An example using the minProperties and maxProperties constraints:

openapi: 3.0.0
...
paths:
  /foo:
    get:
      parameters:
        - in: query
          name: filter
          required: true
          style: form
          explode: true
          schema:
            type: object
            properties:
              username:
                type: string
              site:
                type: string
              survey:
                type: string
            minProperties: 1
            maxProperties: 1
            additionalProperties: false

Using oneOf:

      parameters:
        - in: query
          name: filter
          required: true
          style: form
          explode: true
          schema:
            type: object
            oneOf:
              - properties:
                  username:
                    type: string
                required: [username]
                additionalProperties: false
              - properties:
                  site:
                    type: string
                required: [site]
                additionalProperties: false
              - properties:
                  survey:
                    type: string
                required: [survey]
                additionalProperties: false

Another version using oneOf:

      parameters:
        - in: query
          name: filter
          required: true
          style: form
          explode: true
          schema:
            type: object
            properties:
              username:
                type: string
              site:
                type: string
              survey:
                type: string
            additionalProperties: false
            oneOf:
              - required: [username]
              - required: [site]
              - required: [survey]

Note that Swagger UI and Swagger Editor do not support the examples above yet (as of March 2018). This issue seems to cover the parameter rendering part.

There’s also an open proposal in the OpenAPI Specification repository to support interdependencies between query parameters so maybe future versions of the Specification will have a better way to define such scenarios.

More Related Contents:

  1. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  2. How to specify if a field is optional or required in OpenAPI/Swagger?
  3. How to return an array of objects in SwaggerHub?
  4. How to document dynamic query parameter names in OpenAPI (Swagger)?
  5. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  6. How to define a property that can be string or null in OpenAPI (Swagger)?
  7. Swagger schema properties ignored when using $ref – why?
  8. Swagger 2.0: Multiple Path objects with different paths but same request and response
  9. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  10. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  11. Swagger: wildcard path parameters
  12. How to define an optional parameter in path using swagger
  13. Swagger: “equivalent path already exists” despite different parameters
  14. Re-using model with different required properties
  15. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  16. How not to copy-paste 3 generic error responses in almost all paths?
  17. How to define global parameters in OpenAPI?
  18. Schema object without a type attribute in Swagger 2.0
  19. Swagger: take one or more values from enum
  20. Swagger Inheritance and Composition
  21. Swagger/OpenAPI mock server
  22. Swagger: map of
  23. Use object type query param in swagger documentation
  24. Swagger complex response model with dynamic key value hash maps
  25. How do I include subclasses in Swagger API documentation/ OpenAPI specification using Swashbuckle?
  26. OpenAPI query string parameter with list of objects
  27. OpenAPI path/query parameters nested structure serialization
  28. Combining defintions in Swagger docs
  29. How do I combine multiple OpenAPI 3 specification files together?
  30. Why `additionalProperties` is the way to represent Dictionary/Map in Swagger/OpenAPI 2.0

Leave a Comment