如何记录 OpenAPI (Swagger) 中的动态查询参数名称?
How to document dynamic query parameter names in OpenAPI (Swagger)?
有什么方法可以记录以下查询吗?
GET api/v1/users?name1=value1&name2=value
其中查询参数名称是动态的,将从客户端接收。
我正在使用最新的 Swagger API。
Free-form 可以使用 OpenAPI 3.x 描述查询参数,但不能使用 OpenAPI 2.0 (Swagger 2.0)。该参数必须具有 type: object
和序列化方法 style: form
和 explode: true
。该对象将被序列化为 ?prop1=value1&prop2=value2&...
,其中单个 prop=value 对是对象属性。
openapi: 3.0.3
...
paths:
/users:
get:
parameters:
- in: query
# Arbitrary name. It won't appear in the request URL, but will be used
# in server & client code generated from this OAS document.
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
Free-form 查询参数在 Swagger UI 3.15.0+ 和 Swagger Editor 3.5.6+ 中受支持。在参数编辑器中,以 JSON 对象格式输入参数名称和值,例如{ "prop1": "value1", "prop2": "value2" }
。 “试试看”会将它们作为 param=value
查询参数发送:
虽然不确定 Codegen 支持。
@Helen 的回答即使 Spring 使用 springdoc-openapi-ui 库也能完美运行。
依赖关系:
<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
有什么方法可以记录以下查询吗?
GET api/v1/users?name1=value1&name2=value
其中查询参数名称是动态的,将从客户端接收。
我正在使用最新的 Swagger API。
Free-form 可以使用 OpenAPI 3.x 描述查询参数,但不能使用 OpenAPI 2.0 (Swagger 2.0)。该参数必须具有 type: object
和序列化方法 style: form
和 explode: true
。该对象将被序列化为 ?prop1=value1&prop2=value2&...
,其中单个 prop=value 对是对象属性。
openapi: 3.0.3
...
paths:
/users:
get:
parameters:
- in: query
# Arbitrary name. It won't appear in the request URL, but will be used
# in server & client code generated from this OAS document.
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
Free-form 查询参数在 Swagger UI 3.15.0+ 和 Swagger Editor 3.5.6+ 中受支持。在参数编辑器中,以 JSON 对象格式输入参数名称和值,例如{ "prop1": "value1", "prop2": "value2" }
。 “试试看”会将它们作为 param=value
查询参数发送:
虽然不确定 Codegen 支持。
@Helen 的回答即使 Spring 使用 springdoc-openapi-ui 库也能完美运行。
依赖关系:
<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