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.

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