How to define parameters with square brackets in OpenAPI (Swagger)?

Question

I have an endpoint with query parameters that use square brackets:

GET /info?sort[name]=1&sort[age]=-1

Here, name and age are the field names from my model definition.

How can I write an OpenAPI (Swagger) definition for these parameters?

Answer 1

It depends on which version of OpenAPI (Swagger) you use.

OpenAPI 3.x

The sort parameter can be defined an an object with the name and age properties. The parameter serialization method should be style: deepObject and explode: true.

openapi: 3.0.0
...

paths:
  /info:
    get:
      parameters:
        - in: query
          name: sort
          schema:
            type: object
            properties:
              name:
                type: integer
                example: 1
              age:
                type: integer
                example: -1
          style: deepObject
          explode: true
      responses:
        '200':
          description: OK

This is supported in Swagger UI 3.15.0+ and Swagger-Editor 3.5.6+.

Important: The deepObject serialization style only supports simple non-nested objects with primitive properties, such as in the example above. The behavior for nested objects and arrays of objects is not defined.

In other words, while we can define

?param[foo]=...&param[bar]=...

there's currently no way to define more nested query parameters such as

?param[0][foo]=...&param[1][bar]=...
or
?param[foo][0][smth]=...&?param[foo][1][smth]=

If you need the syntax for deeply nested query parameters, upvote and follow this feature request:
Support deep objects for query parameters with deepObject style

OpenAPI 2.0 (Swagger 2.0)

sort[name] and sort[age] need to be defined as individual parameters:

swagger: '2.0'
...
paths:
  /info:
    get:
      parameters:
        - in: query
          name: sort[name]
          type: integer
        - in: query
          name: sort[age]
          type: integer
      responses:
        200:
          description: OK