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
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
This works with both OpenAPI 3.0 and OpenAPI 3.1.