swagger - 如何在OpenAPI(Swagger)中记录动态查询参数名称？

Question

有什么方法可以记录以下查询？

GET api/v1/users?name1=value1&name2=value

查询参数名称是动态的，将从客户端接收。

我正在使用最新的Swagger API。

Answer 1

可以使用OpenAPI 3.0描述自由格式的查询参数，但不能使用OpenAPI 2.0（Swagger 2.0）描述。该参数应具有type: object，并带有序列化方法style: form和explode: true。该对象将序列化为?prop1=value1&prop2=value2&...，其中各个prop = value对是对象属性。

openapi: 3.0.1
...
paths:
  /users:
    get:
      parameters:
        - in: query
          name: params
          schema:
            type: object
            # If the parameter values are of specific type, e.g. string:
            additionalProperties:
              type: string
            # If the parameter values can be of different types
            # (e.g. string, number, boolean, ...)
            # additionalProperties: true

          # `style: form` and `explode: true` is the default serialization method
          # for query parameters, so these keywords can be omitted
          style: form
          explode: true

Swagger UI 3.15.0+和Swagger Editor 3.5.6+支持自由格式查询参数。在参数编辑器中，以JSON对象格式输入参数名称和值，例如 { "prop1": "value1", "prop2": "value2" }。 “试用”将其作为 param=value查询参数发送：



虽然不确定Codegen支持。