I am starting to learn API documentation with YAML. I have the below YAML and my query params are id, firstName and lastName. The user should provide either id or any of firstName or lastName.
- If id is provided, lastName and firstName need not be provided
- if lastName or firstName is provided, id need not be provided
Some what like id or (firstName or lastName).
So how can I define this rule in my YAML. I think oneOf, anyOf constructs can be used for the same in request body but how can I achieve this in a query param ?
<code>openapi: 3.0.1
info:
title: Example API
version: 1.0.0
paths:
/users:
get:
summary: Get user information by ID or name
parameters:
- name: id
in: query
schema:
type: integer
required: false
description: User ID
- name: firstName
in: query
schema:
type: string
required: false
description: First name of the user
- name: lastName
in: query
schema:
type: string
required: false
description: Last name of the user
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: string
example: User information retrieved successfully
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid request parameters
</code>
<code>openapi: 3.0.1
info:
title: Example API
version: 1.0.0
paths:
/users:
get:
summary: Get user information by ID or name
parameters:
- name: id
in: query
schema:
type: integer
required: false
description: User ID
- name: firstName
in: query
schema:
type: string
required: false
description: First name of the user
- name: lastName
in: query
schema:
type: string
required: false
description: Last name of the user
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: string
example: User information retrieved successfully
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid request parameters
</code>
openapi: 3.0.1
info:
title: Example API
version: 1.0.0
paths:
/users:
get:
summary: Get user information by ID or name
parameters:
- name: id
in: query
schema:
type: integer
required: false
description: User ID
- name: firstName
in: query
schema:
type: string
required: false
description: First name of the user
- name: lastName
in: query
schema:
type: string
required: false
description: Last name of the user
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: string
example: User information retrieved successfully
'400':
description: Bad request
content:
application/json:
schema:
type: object
properties:
error:
type: string
example: Invalid request parameters