Describing a multi-value querystring parameter in OpenAPI

Featured image for sharing metadata for article

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:

      # 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
        type: array
          $ref: '#/components/schemas/PostType'
      type: string
        - 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.

Written by Jamie Tanna's profile image Jamie Tanna on , and last updated on .

Content for this article is shared under the terms of the Creative Commons Attribution Non Commercial Share Alike 4.0 International, and code is shared under the Apache License 2.0.

#blogumentation #openapi #api #json-patch.

Also on:

This post was filed under articles.

Interactions with this post

Interactions with this post

Below you can find the interactions that this page has had using WebMention.

Have you written a response to this post? Let me know the URL:

Do you not have a website set up with WebMention capabilities? You can use Comment Parade.