Conditional dependencies in form data can be expressed in OpenAPI 3, but not in OpenAPI 2.0 (swagger: 2.0).
OpenAPI 3.1
This example uses if..then, a new construct in OAS 3.1.
openapi: 3.1.0
...
paths:
/login:
post:
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/LoginRequest'
responses:
'200':
description: Successful response
components:
schemas:
LoginRequest:
type: object
required:
- type
- password
properties:
type:
type: string
enum: [email, phone]
email:
type: string
country:
type: string
phone:
type: string
password:
type: string
# Conditional dependencies
allOf:
# If type="email", then the `email` field is required
- if:
properties:
type:
const: email
then:
required: [email]
# If type="phone", then the `country` and `phone` fields are required
- if:
properties:
type:
const: phone
then:
required: [country, phone]
OpenAPI 3.0.x
In OAS 3.0, you can use the following oneOf construct to express these conditions.
openapi: 3.0.3
...
paths:
/login: ... # The path definition is the same as in the previous example
components:
schemas:
LoginRequest:
type: object
required:
- type
- password
properties:
type:
type: string
enum: [email, phone]
email:
type: string
country:
type: string
phone:
type: string
password:
type: string
# Conditional dependencies
oneOf:
# If type="email" ...
- properties:
type:
enum: [email]
# ... then the `email` field is required
required: [email]
# If type="phone" ...
- properties:
type:
enum: [phone]
# ...then the `country` and `phone` fields are required
required: [country, phone]
OpenAPI 2.0
In OpenAPI 2.0, the most you can do is define the conditionally required parameters (email, country and phone in your example) as optional and mention the dependencies in the operation description and/or parameter descriptions.
swagger: '2.0'
...
paths:
/login:
post:
...
parameters:
- name: type
type: string
in: formData
enum: [email, phone]
required: true
- name: email
type: string
in: formData
description: Required if type=email
- name: country
type: string
in: formData
description: Required if type=phone
- name: phone
type: string
in: formData
description: Required if type=phone
- name: password
type: string
in: formData
required: true
