How to define mutually exclusive query parameters

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

What about changing your API design ? Currently you have one method, 3 parameters. If I understand well, user must always provide exactly one parameter, and two remaining ones must be unset.

For me, API would be more usable with three endpoints -like

/user/byName?name=
/user/bySite?name=
/user/bySurvey?name=

Answer 2

An alternative is to pass in a filter type parameter with an enum, and a filter value with the value to use.

Example at: https://app.swaggerhub.com/api/craig_bayley/PublicAPIDemo/v1

It can be required or not, as you choose. However if one is required, they should both be.

Answer 3

Unfortunately this isn't possible in Swagger currently. "required" is just a boolean and there's no way to represent interdependencies between parameters.

Best you can do is make clear the requirements in the parameter descriptions and also put in a custom 400 Bad Request description along the same lines.

(There's a bit of discussion at https://github.com/swagger-api/swagger-spec/issues/256 about possible ways of implementing this in the next version of Swagger)

Answer 4

Mutually exclusive parameters are possible (sort of) in OpenAPI 3.0:

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