如何在 OpenAPI (Swagger) 中用方括号定义参数？

Question

我有一个端点，其查询参数使用方括号：

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

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

如何为这些参数编写 OpenAPI (Swagger) 定义？

Answer 1

这取决于您使用的 OpenAPI (Swagger) 版本。

OpenAPI 3.x

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+ 支持此功能。

重要提示： deepObject 序列化样式仅支持具有原始属性的简单非嵌套对象，如上例所示。嵌套对象和对象数组的行为 is not defined.

换句话说，虽然我们可以定义

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

目前无法定义更多嵌套查询参数，例如

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

如果您需要深层嵌套查询参数的语法，请投票并关注此功能请求：
Support deep objects for query parameters with deepObject style

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

如何在 OpenAPI (Swagger) 中用方括号定义参数？

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

swagger

openapi

OpenAPI 3.x

OpenAPI 2.0 (Swagger 2.0)