How to document dynamic query parameter names in OpenAPI (Swagger)?
Solution 1
Free-form query parameters can be described using OpenAPI 3.x, but not OpenAPI 2.0 (Swagger 2.0). The parameter must have type: object
with the serialization method style: form
and explode: true
. The object will be serialized as ?prop1=value1&prop2=value2&...
, where individual prop=value pairs are the object properties.
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
Free-form query parameters are supported in Swagger UI 3.15.0+ and Swagger Editor 3.5.6+. In the parameter editor, enter the parameter names and values in the JSON object format, e.g. { "prop1": "value1", "prop2": "value2" }
. "Try it out" will send them as param=value
query parameters:
Not sure about Codegen support though.
Solution 2
@Helen's answer works perfectly even with Spring using the springdoc-openapi-ui library.
Dependency:
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-ui</artifactId>
<version>1.1.43</version>
</dependency>
In the API function, add the following parameter:
@Parameter(in=ParameterIn.QUERY,
name="params", style=ParameterStyle.FORM,
schema=@Schema(type="object"), explode=Explode.TRUE,
example="") String paramsObj
Sharad Ahire
Updated on July 01, 2022Comments
-
Sharad Ahire almost 2 years
Is there any way to document the following query?
GET api/v1/users?name1=value1&name2=value
where the query parameter names are dynamic and will be received from the client.
I'm using the latest Swagger API.
-
abisheksampath over 5 yearsThanks! this was what I needed. Also, do you know if there is a way to export API documentation from a Spring Boot application for OpenAPI 3.0 ?
-
Helen over 5 years@abisheksampath sorry I'm not familiar with Spring Boot. If you mean Springfox specifically it doesn't seem to support OpenAPI 3.0 yet (as of November 2018).
-
GuanacoBE over 4 yearsThis can not work with a
Map
. The type is ignored : github.com/springdoc/springdoc-openapi/blob/master/… -
Maria Ines Parnisari almost 4 yearsThis doesn't work with codegen. It throws an error
Cannot convert undefined or null to object
when accessingschema.properties
-
Helen almost 4 years@MariaInesParnisari send a bug report to the codegen project that you used.