Describing a multi-value querystring parameter in OpenAPI
If you're building an API, you may want to have the option of querying or filtering multiple values, and want to make it clear to a consumer, through your OpenAPI spec.
Let's say that we want to allow a query which includes a parameter post-type, which can have the values article, bookmark and reply.
To do this with OpenAPI, we'd construct the following:
components:
parameters:
PostType:
# this doesn't have to include `[]`, but it's a good indicator that
# it's a multi-value option, even though it's a valid HTTP thing to do,
# to provide multiple values with just `post-type`
name: "post-type[]"
in: query
explode: true
schema:
type: array
items:
$ref: '#/components/schemas/PostType'
schemas:
PostType:
type: string
enum:
- article
- bookmark
- reply
The important thing here is the explode and marking the items as an array.
This works with both OpenAPI 3.0 and OpenAPI 3.1.
