如何在OpenAPI（Swagger）中记录动态查询参数名称？

Question

有没有办法记录以下查询？

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

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

我正在使用最新的Swagger API。

Answer 1

可以使用OpenAPI 3.0来描述自由格式查询参数，但不能使用OpenAPI 2.0（Swagger 2.0）来描述。该参数应为content，序列化方法为type: object和style: form。该对象将序列化为explode: true，其中单个 prop = value 对是对象属性。

?prop1=value1&prop2=value2&...

Swagger UI 3.15.0+和Swagger Editor 3.5.6+支持自由格式查询参数。在参数编辑器中，以JSON对象格式输入参数名称和值，例如： 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 。 ＆＃34;尝试一下＆＃34;将它们作为{ "prop1": "value1", "prop2": "value2" }查询参数发送：

不确定Codegen支持。

Answer 2

@Helen的答案即使在使用springdoc-openapi-ui库的Spring中也能很好地工作。

依赖性：

 <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.43</version>
 </dependency>

在API函数中，添加以下参数：

 @Parameter(in=ParameterIn.QUERY,
            name="params", style=ParameterStyle.FORM,
            schema=@Schema(type="object"), explode=Explode.TRUE,
            example="") String paramsObj