Conditional Query Parameters in Swagger [duplicate] - swagger

Question

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

Answer 1

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

Answer 2

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.

Answer 3

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.

Answer 4

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.

Answer 5

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