带括号和变量名的OpenAPI参数

Question

我正在开发一个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

这个答案几乎是我想要做的，我只是找不到一种方法来定义括号内的值为“任何字符串”，而不是已知名称的列表。

Answer 1

search参数可以定义为具有deepobject序列化样式和minproperties:1的自由格式对象，以强制搜索查询中至少存在一个字段。

确保您使用的是OpenAPI3.0(OpenAPI:3.0.x)，而不是OpenAPI2.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