如何在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属性将参数定义为一个对象。参数序列化方法应为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