如何在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的支持.