# Documenting filters using OpenAPI

**URL:** <https://discuss.jsonapi.org/t/documenting-filters-using-openapi/1432>\
**Category:** Uncategorized\
**Created:** [November 27, 2018, 11:23am UTC](https://discuss.jsonapi.org/t/documenting-filters-using-openapi/1432 "2018-11-27T11:23:30Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![waghanza](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/waghanza/32/582_2.png) [@waghanza](https://discuss.jsonapi.org/u/waghanza)\
**Post date:** [November 27, 2018, 11:23am UTC](https://discuss.jsonapi.org/t/documenting-filters-using-openapi/1432/1 "2018-11-27T11:23:30Z")

</div>

Hi,

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

Json Api specification supports pagination =\> [https://jsonapi.org/format/#fetching-pagination](https://jsonapi.org/format/#fetching-pagination)

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

Regards,

---

<div class="post-metadata">

**Author:** ![cmeeren](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/cmeeren/32/596_2.png) [@cmeeren](https://discuss.jsonapi.org/u/cmeeren)\
**Post date:** [April 25, 2019, 8:38am UTC](https://discuss.jsonapi.org/t/documenting-filters-using-openapi/1432/2 "2019-04-25T08:38:20Z")

</div>

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
```

---

<div class="post-metadata">

**Author:** ![ahx](https://sea2.discourse-cdn.com/flex016/user_avatar/discuss.jsonapi.org/ahx/32/624_2.png) [@ahx](https://discuss.jsonapi.org/u/ahx)\
**Post date:** [July 16, 2019, 1:34pm UTC](https://discuss.jsonapi.org/t/documenting-filters-using-openapi/1432/3 "2019-07-16T13:34:55Z")

</div>

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](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#style-values)

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

```