我有一个带有使用方括号的查询参数的端点:

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

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

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

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

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

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

推荐答案

这取决于你使用的 OpenAPI (Swagger) 版本.

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

sort 参数可以定义为具有 name 和 age 属性的对象.参数序列化方法应该是style: deepObject和explode: true.

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

这在 Swagger UI 3.15.0+ 和 Swagger-Editor 3.5.6+ 中受支持.

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

重要提示: deepObject 序列化样式仅支持具有原始属性的简单非嵌套对象，例如上面的示例.嵌套对象和对象数组的行为未定义.

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]=

如果您需要深度嵌套查询参数的语法，请点赞并关注此功能请求:支持 deepObject 样式的查询参数的深层对象

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

sort[name] 和 sort[age] 需要定义为单独的参数:

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