OpenAPI query string parameter with list of objects

Question

I am trying to document with OpenAPI a query string which look like

filtered[0][id]=code&filtered[0][value]=12345

and contains a list of object with properties id and value.

My yaml documentation looks like the following

parameters: - name: filtered in: query description: filters to be applied explode: true style: deepObject schema: type: array items: properties: id: description: name of the field to be filtered type: string value: description: value of the filter type: object

The problem is the following: it looks like the style: deepObject option works only for one level, and not at the second level where my objects actually are. That is, it expects a query string like

?sorted[0]=%7B%0A%20%20%22id%22%3A%20%22string%22%2C%0A%20%20%22value%22%3A%20true%0A%7D

with the object not serialized as an array with id and value keys.

Is there a way to solve this?

deepobject is still not native jason just enumeration of all object properties or elements — Serge
– Serge, Commented Oct 19, 2018 at 13:01
@serge i would like to encode my query string as filtered[0][id]=code&filtered[0][value]=12345 — marcosh
– marcosh, Commented Oct 19, 2018 at 13:09
Well by name deep object aplies to objects. Is it an option to put your list inside an object — Serge
– Serge, Commented Oct 19, 2018 at 13:29
no, it is not an option. The frontend is using a library (react-table) which uses that format. That is what I need to document, I can't change it — marcosh
– marcosh, Commented Oct 19, 2018 at 13:32

Helen · Accepted Answer · 2021-02-19 10:22:28Z

This is not possible as of OpenAPI 3.1

OpenAPI 3.0/3.1 Specifications currently defines the deepObject behavior only for simple objects (with primitive properties) such as

{ "id": 5, "name": "Bob" }

but not for arrays and not for nested objects.

Since the behavior for arrays and nested objects is not defined, there's really no way to describe your query string. Technically, the only way would be to define filtered[0][id], filtered[0][value], etc. as individual query parameters.

If you are designing a new API (rather than describing an existing one), consider passing the array of objects in the request body instead.

Seems that the main use case for nested objects in the query parameters is filtering and searching, which implies GET. Popular opinion seems to indicate that using POST with search values in the request body is a bad idea.
We used GET in the end and used pattern in the schema description for the parameter to match a regex. Its not great but it works for very basic nested objects

Serge · Accepted Answer · 2021-06-02 17:11:23Z

As name implies, :), deepObject style only "provides a simple way of rendering nested objects", not arrays. At the least according to Version 3.0.1 it applies only to objects.

Note that even nested objects might be not yet supported by tools because the specification "does not provide such examples".

So your format is not compatible with Open API, yet may be you can define you query as parameters which follow a regex. I such cases usually I do my best yet provide some explanation

https://swagger.io/specification/

Update. Apparently, after somebody demanded a 'descriptive error' message for nested objects, a patch (PR) to support nested objects was suggested at https://github.com/swagger-api/swagger-js/pull/1450 . Regretfully it was decided not to incorporate this feature, and PR 1450 was rejected.

Happy Coder · Accepted Answer · 2022-10-03 21:00:59Z

I know it's an old question, but starting open api 3 there is a support for what you looking for https://swagger.io/docs/specification/describing-parameters/#schema-vs-content.

it was reported as a bug that was fixed with openapi generator 6.0.1 + https://github.com/OpenAPITools/openapi-generator/issues/4808

parameters: - in: query name: filter content: application/json: schema: schema: $ref: "#/components/schemas/Filter"

For some reason this is not working for me. When the object comes through in the controller the values are not mapped and will come through as null

Collectives™ on Stack Overflow

OpenAPI query string parameter with list of objects

3 Answers 3

3 Comments

Comments

1 Comment

Linked

Hot Network Questions