OpenAPI - how to describe query parameters?

Question

I'm trying to figure out how to document two of my query parameters in OpenAPI.

Filtering

My filtering follows the recommendations of JSON:API, which takes the form of, for example:

• ?filter[post]=1,2,3
• ?filter[post]=1,2,3&filter[author]=5

The filter key is an associative array that can contain a set list of resource names in my API. The value assigned to each filter key is either a single id or list of comma separated ids.

Sorting

For sorting also follows the JSON:API recommendation, so something like these:

• ?sort=age
• ?sort=age,-height

The sort query parameter is assigned the value of one sort field or list of comma separated sort fields. Note that the minus sign that prefixes the height field indicates a descending sort.

Question

How do I represent the my filtering and sorting in OpenAPI?

For example, I'm not sure it's possible for me to specify that the filter key is an associative array, or that it accepts a comma separated list of ids. Almost the same issue for sort: how to represent a comma separated list of sort fields?

Answer 1

This may be a bit old but I'm currently documenting an API whose sort, filter and dynamic relationship includes adheres to the JSON API spec and I just figured out how to properly document the filter query parameter. The below is written in JSON but I hope you'd be able to adapt it to fit your needs if you're writing YAML

{
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "id": {
          "description": "Id of the user",
          "type": "string"
        },
        "referrer_id": {
          "description": "The id of the user that referred the user",
          "type": "string"
        },
        "email_verified": {
          "description": "Whether the user has verified their email address",
          "type": "boolean"
        },
        "trashed": {
          "description": "Whether the user has been soft deleted",
          "type": "string",
          "enum": [
            "with",
            "only"
          ]
        }
      }
    },
    "in": "query",
    "name": "filter",
    "description": "Really long description.........",
    "style": "deepObject",
    "explode": true,
    "allowReserved": true
  }

To document sorting, you can follow the example included here which is also written below

parameters:
  - in: query
    name: ids
    description: One or more IDs
    required: true
    schema:
      type: array
      items:
        type: integer
    style: form
    explode: false
    examples:
      oneId:
        summary: Example of a single ID
        value: [5]   # ?ids=5
      multipleIds:
        summary: Example of multiple IDs
        value: [1, 5, 7]   # ?ids=1,5,7