How to document dynamic query parameter names in OpenAPI (Swagger)?

Question

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.

Helen · Accepted Answer · 2022-06-02 10:25:11Z

47

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.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 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:

Free-form query parameters in Swagger UI

Not sure about Codegen support though.

edited Jun 2, 2022 at 10:25

answered Mar 31, 2018 at 12:30

Helen

99.8k17 gold badges280 silver badges352 bronze badges

Sign up to request clarification or add additional context in comments.

4 Comments

abisheksampath Over a year ago

Thanks! 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 a year ago

@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).

Maria Ines Parnisari Over a year ago

This doesn't work with codegen. It throws an error Cannot convert undefined or null to object when accessing schema.properties

Helen Over a year ago

@MariaInesParnisari send a bug report to the codegen project that you used.

Helen · Accepted Answer · 2019-09-27 19:33:25Z

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

edited Sep 27, 2019 at 19:33

Helen

99.8k17 gold badges280 silver badges352 bronze badges

answered Sep 26, 2019 at 9:34

Nischal Revooru

3033 silver badges10 bronze badges

1 Comment

GuanacoBE Over a year ago

This can not work with a Map. The type is ignored : github.com/springdoc/springdoc-openapi/blob/master/…

Collectives™ on Stack Overflow

How to document dynamic query parameter names in OpenAPI (Swagger)?

2 Answers 2

4 Comments

1 Comment

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

4 Comments

1 Comment

Your Answer

Sign up or log in

Post as a guest

Linked

Related