如何在OpenAPI（Swagger）中使用方括号定义参数？

Question

我的端点的查询参数使用方括号：

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

此处，name和age是我的模型定义中的字段名称。

如何为这些参数编写OpenAPI（Swagger）定义？

Answer 1

这取决于您使用的OpenAPI（Swagger）版本。

OpenAPI 3.0

sort参数可以定义为具有name和age属性的对象。参数serialization method应为style: deepObject和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

Swagger UI 3.15.0+和Swagger-Editor 3.5.6 +。

支持此功能

OpenAPI 2.0（Swagger 2.0）

需要将

sort[name]和sort[age]定义为单个参数：

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