3

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.

Bill
  • 3,059
  • 3
  • 31
  • 47
  • `filter` and `order[]` are objects in OpenAPI terms. Where's the array? – Helen Sep 01 '17 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 Sep 02 '17 at 00:05
  • 1
    @HelderSepu: Maybe the OP is using the design-first approach, that is generating code from the spec and not vice versa. – Helen Sep 04 '17 at 08:01
  • Related: [Use object-type query param in OpenAPI](https://stackoverflow.com/q/38187187/113116), [How to define parameters with square brackets in OpenAPI?](https://stackoverflow.com/q/48491688/113116) – Helen Oct 02 '19 at 10:49

2 Answers2

3

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
Helen
  • 87,344
  • 17
  • 243
  • 314
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

Happy Coder
  • 1,293
  • 1
  • 19
  • 35