如何在OpenAPI（Swagger）中记录动态查询参数名？

Great question! When you have an endpoint like GET api/v1/users where clients send dynamic query parameter names (e.g., name1=value1&name2=value2), the latest OpenAPI 3.x specification (including 3.1) has a clean way to document this behavior.

Here's how to do it step by step:

Core Approach #

Use a query parameter type combined with style: form, explode: true, and additionalProperties in the schema to describe the dynamic key-value pairs. This tells tools like Swagger UI to render support for arbitrary client-defined parameter names.

Example OpenAPI YAML #

openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0
paths:
  /api/v1/users:
    get:
      summary: Fetch users with dynamic client-defined filters
      parameters:
        - name: dynamic_filters
          in: query
          description: >
            Dynamic filter parameters where the key is a client-defined name (e.g., `name1`, `email`)
            and the value is the filter criteria to apply.
          required: false
          style: form
          explode: true
          schema:
            type: object
            additionalProperties:
              type: string
              description: The value for the corresponding dynamic filter parameter

Breakdown of Key Components #

• name: dynamic_filters: This is just a logical identifier for documentation purposes—it won't appear in actual requests. It helps clarify what the dynamic parameters represent.
• style: form + explode: true: These settings ensure that each key-value pair in the object is expanded into a separate query parameter (e.g., an object {name1: "Alice", email: "alice@example.com"} becomes ?name1=Alice&email=alice@example.com).
• additionalProperties: Defines the data type for the values of your dynamic parameters. In the example above, values are strings, but you can adjust this to number, boolean, or even a nested schema if needed.

Adding Constraints (Optional) #

If you want to restrict the allowed dynamic parameter names (e.g., only allow keys starting with name followed by a number), use the propertyNames keyword to enforce a regex pattern:

schema:
  type: object
  propertyNames:
    pattern: "^name\\d+$"  # Only allows keys like `name1`, `name2`, etc.
  additionalProperties:
    type: string

How This Looks in Swagger UI #

Swagger UI will render an interactive section where users can add multiple key-value pairs, mirroring the dynamic parameter behavior clients will use. This makes it clear to consumers how to interact with the endpoint.

Hope this helps you properly document your dynamic query parameters! Feel free to adjust the schema or constraints to match your specific use case.

内容的提问来源于stack exchange，提问作者Sharad Ahire