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
andfirstName
need not be provided - if
lastName
orfirstName
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 ?
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
2