Swagger/OpenAPI spec for arrays of objects in URL query parameter

Question

Assume I have a URL which takes a path of: ?filter[id]=1&filter[name]=bob&order[][name]=asc&order[][age]=desc

How would one be able to convert this into swagger documentation, specifically, array of objects and arrays as the query parameter.

filter and order[] are objects in OpenAPI terms. Where's the array? — Helen
– Helen, Commented Sep 1, 2017 at 18:14
There are tools out there to generate the swagger doc for your api for almost every language. Use one of those that way you don't have to worry about swagger just code your api. — Helder Sepulveda
– Helder Sepulveda, Commented Sep 2, 2017 at 0:05
@HelderSepu: Maybe the OP is using the design-first approach, that is generating code from the spec and not vice versa. — Helen
– Helen, Commented Sep 4, 2017 at 8:01
Related: Use object-type query param in OpenAPI, How to define parameters with square brackets in OpenAPI? — Helen
– Helen, Commented Oct 2, 2019 at 10:49

Helen · Accepted Answer · 2019-10-02 10:47:20Z

Your example is not an array of objects but two separate object parameters - filter and order[], each serialized using the deepObject style (supported in OpenAPI 3.0). You can describe these parameters as follows:

openapi: 3.0.2
...

paths:
  /something:
    get:
      # ?filter[id]=1&filter[name]=bob&order[][name]=asc&order[][age]=desc
      parameters:
        - in: query
          name: filter
          schema:
            type: object
            properties:
              id:
                type: integer
                example: 1
              name:
                type: string
                example: bob
          style: deepObject

        - in: query
          name: order[]
          schema:
            type: object
            properties:
              name:
                type: string
                example: asc
              age:
                type: string
                example: desc
          style: deepObject

Happy Coder · Accepted Answer · 2022-02-18 16:08:04Z

0

It's an old question, but the answer above is misleading

array of objects s is not supported in OpenAPI 3.0/3.1 Specifications currently defines

see the question OpenAPI query string parameter with list of objects

answered Feb 18, 2022 at 16:08

Happy Coder

1,4233 gold badges25 silver badges42 bronze badges

Collectives™ on Stack Overflow

Swagger/OpenAPI spec for arrays of objects in URL query parameter

2 Answers 2

Comments

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related