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

by

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.

More Related Contents:

  1. Swagger: “equivalent path already exists” despite different parameters
  2. How to write OpenAPI 3 (Swagger) specification for property name in `map` object?
  3. Swagger: How to have a property reference a model in OpenAPI 2.0 (i.e. nest the models)?
  4. How to specify if a field is optional or required in OpenAPI/Swagger?
  5. How to return an array of objects in SwaggerHub?
  6. How to define a mixed-type array (with different element types) in OpenAPI 2.0?
  7. How can I represent ‘Authorization: Bearer ‘ in a Swagger Spec (swagger.json)
  8. How to define a property that can be string or null in OpenAPI (Swagger)?
  9. Swagger schema properties ignored when using $ref – why?
  10. How to define mutually exclusive query parameters in Swagger (OpenAPI)?
  11. Swagger 2.0: Multiple Path objects with different paths but same request and response
  12. Swagger/OpenAPI – use $ref to pass a reusable defined parameter
  13. How to convert OpenAPI 2.0 to OpenAPI 3.0? [closed]
  14. Swagger complex response model with dynamic key value hash maps
  15. Swagger: wildcard path parameters
  16. How to define an optional parameter in path using swagger
  17. Re-using model with different required properties
  18. How not to copy-paste 3 generic error responses in almost all paths?
  19. How to define global parameters in OpenAPI?
  20. Schema object without a type attribute in Swagger 2.0
  21. Swagger: take one or more values from enum
  22. How to export swagger.json (or yaml)
  23. Swagger/OpenAPI mock server
  24. How to add multiple example values in swagger properties?
  25. Swagger HashMap property type
  26. Post a json body with swagger
  27. Swagger API which is having query string
  28. How to add multiple example values for an array in OpenAPI/Swagger?
  29. Sending cookie session id with Swagger 3.0
  30. How do I combine multiple OpenAPI 3 specification files together?

Leave a Comment