84

I have a swagger 2.0 resource defined below. How can I make "param1 or param2" required? Caller has to pass either param1 or param2.

/some/res:
put:
  summary: some resource
  responses:
    200:
      description: Successful response
      schema:
        $ref: '#/definitions/SomeResponse'
  parameters:
    - name: param1
      type: string
      description: param1
      in: formData
      required: false
    - name: param2
      type: string
      description: param2
      in: formData
      required: false
Vineet Bhatia
  • 2,469
  • 4
  • 30
  • 28
  • Related (or duplicate): [How to define mutually exclusive query parameters in Swagger (OpenAPI)?](https://stackoverflow.com/q/21134029/113116) – Helen Mar 09 '18 at 17:42

5 Answers5

71

OpenAPI (fka Swagger) Specification does not support conditional or mutually exclusive parameters (of any type).

There is an open feature request:
Support interdependencies between query parameters

Helen
  • 87,344
  • 17
  • 243
  • 314
Ron
  • 14,160
  • 3
  • 52
  • 39
17

The specific scenario in this question – a POST/PUT/PATCH request with a form-data body that contains either param1 or param2 – can be defined using OpenAPI 3.0 and oneOf:

openapi: 3.0.0
...

paths:
  /some/res:
    put:
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  properties:
                    param1:
                      type: string
                  required:
                    - param1
                  additionalProperties: false
                - type: object
                  properties:
                    param2:
                      type: string
                  required:
                    - param2
                  additionalProperties: false

Note for Swagger UI users: form-data UI and example rendering for oneOf schemas are not available for OpenAPI 3.0 definitions yet.

Helen
  • 87,344
  • 17
  • 243
  • 314
  • 2
    How about using `oneOf` against query parameters instead of body schema? I guess this is still not supported? – hris.to Aug 31 '18 at 13:15
  • @hris.to I'm not sure, it's hard to say without seeing the actual spec. If something doesn't work in Swagger UI, I'd suggest that you file an issue here: https://github.com/swagger-api/swagger-ui/issues – Helen Sep 05 '18 at 13:55
8

In the Parameter Dependencies section of the Describing Parameters Swagger docs:

Swagger does not support parameter dependencies and mutually exclusive parameters. There is an open feature request at https://github.com/OAI/OpenAPI-Specification/issues/256.

As of June 2017, that issue had 21 upvotes, making it the third most upvoted issue in the project.

Trenton
  • 11,678
  • 10
  • 56
  • 60
3

The Swagger specification does not support conditional requirement or inclusion/exclusion of parameters.

What I would suggest is to state clearly in the description your rules for inclusion/exclusion of query parameters. Then using a validation framework, which depends on your language (i.e. javax.validation for Java, restify-validation for restify, etc.), validate the parameters accordingly.

Gene Ames
  • 31
  • 1
1

You can use a simple trick. Use different requests with the same route but define different "home made" query parameters using "path" type instead of the "query". For some interdependent logic between parameters, put the logic in your API and define specific responses based on correct/uncorrect requests. You can also protect the URL definition on the client-side, but let the stuff where they belong.

/myUrl/myRoute/?queryPara1={query1}?queryPara2={query2}:
get:
  parameters:
    - in: path
      name: query1
      schema:
        type: string
    - in: path
      name: query2
      schema:
        type: string 

/myUrl/myRoute/?queryPara3={query3}?queryPara4={query4}:
get:
  parameters:
    - in: path
      name: query3
      schema:
        type: string
    - in: path
      name: query4
      schema:
        type: string
jonaeschimann
  • 11
  • 2