Documenting filters using OpenAPI

1

Hi,

We use openapi (aka swagger v3) to document our api.

Json Api specification supports pagination => https://jsonapi.org/format/#fetching-pagination

How cn I document my api to specify wich filter is available for each endpoint ?

Regards,

2

I simply use normal query parameter documentation:

- in: query
  name: "filter[orderType]"
  required: true
  description: Filter on the `orderType` field.
  schema:
    type: string
    enum:
      - quote
      - order
1 Like
3

I am using a nested schema to describe the filter query parameter via normal JSON Schema. This follows the “deepObject” style of parameter serialization (as far as I understand this). See https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#style-values

        - name: filter
          in: query
          description: Filter by thing
          required: true
          schema:
            type: object
            additionalProperties: false
            properties:
              things:
                description: ID of thing
                type: string
1 Like