We have an API which I am looking to generate an OpenAPI spec for. The API conforms to a JSON:API standard and I have an issue defining the query filter parameters when doing gets on collections.
The basic form is filter[ attribute ][ operation ]= <value(s)> as derived from the spec.
Here is an example of a set of filters applied to a GET in our API.
filter[kind][in]=bot,agent&filter[organisation.id][eq]=ee780119-8750-4895-8acbc6-c02fe838924f&page[limit]=10&page[offset]=0&filter[customer.phones][any-like]=%2b88600000000,%2b89666666666
Now, the attribute can be any dot path to an attribute in the object and the operation can be any one of a set of supported operations for that attribute (in, eq, any-like, between, etc.).
This gives us the flexibility we want but I struggle to define it in an OpenAPI schema to aid consumers of the API definition. The pagination parameters are easy to do as I can just define them as follows or use a deep object but this does not extend to the filter[][] case.
- in: query
name: page[offset]
- in: query
name: page[limit]
But how can I define filters? Or in general what is the best approach?
