带括号和变量名的 OpenAPI 参数

【问题标题】：OpenAPI parameter with brackets and variable name带括号和变量名的 OpenAPI 参数
【发布时间】：2019-05-23 15:58:41
【问题描述】：

我正在开发一个 API，它允许使用以下 URL 进行搜索：

GET https://example.com/api/data?search[field1]=value1
GET https://example.com/api/data?search[field2]=value2
GET https://example.com/api/data?search[field1]=value1&search[field2]=value2

基本上，您可以通过将字段名称放在括号中来搜索一个或多个字段值。问题是，字段名称是由用户在其设置中定义的。字段名称将是一个字符串，否则在全局级别上无法提前知道。

This answer 几乎是我想要做的，我只是找不到将括号内的值定义为“任何字符串”而不是已知名称列表的方法。

【问题讨论】：

标签： openapi swagger-editor

【解决方案1】：

search 参数可以定义为 free-form object 与 deepObject serialization style 和 minProperties: 1 以强制在搜索查询中至少存在一个字段。

确保您使用的是 OpenAPI 3.0 (openapi: 3.0.x) 而不是 OpenAPI 2.0 (swagger: "2.0")；后者不支持查询字符串中的对象。

openapi: 3.0.2
...

paths:
  /api/data:
    get:
      parameters:
        - in: query
          name: search
          required: true
          schema:
            type: object
            additionalProperties: true  # Default value, may be omitted
            minProperties: 1
            # Optional example to use as a starting value for "try it out" in Swagger UI
            example: >
              {
                "field1": "value1",
                "field2": "value2"
              }
          style: deepObject
          explode: true
      responses:
        200:
          description: OK

【讨论】：