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

Question

I have a series of parameters in Swagger like this

                    "parameters": [                     {                         "name": "username",                         "description": "Fetch username by username/email",                         "required": false,                         "type": "string",                         "paramType": "query"                     },                     {                         "name": "site",                         "description": "Fetch username by site",                         "required": false,                         "type": "string",                         "paramType": "query"                     },                     {                         "name": "survey",                         "description": "Fetch username by survey",                         "required": false,                         "type": "string",                         "paramType": "query"                     }                 ], 

One parameter MUST be filled out but it doesn't matter which one, the others can be left blank. Is there a way to represent this in Swagger?

Answer 1

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.