如何在 OpenAPI (Swagger) 中记录动态查询参数名称? [英] How to document dynamic query parameter names in OpenAPI (Swagger)?

问题描述

有没有办法记录以下查询?

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.

我正在使用最新的 Swagger API.

I'm using the latest Swagger API.

推荐答案

可以使用 OpenAPI 3.x 描述自由格式的查询参数，但不能使用 OpenAPI 2.0 (Swagger 2.0).该参数必须具有 type: object 和序列化方法 style: form 和 explode: true.该对象将被序列化为 ?prop1=value1&prop2=value2&...，其中各个 prop=value 对是对象属性.

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

Swagger UI 3.15.0+ 和 Swagger Editor 3.5.6+ 支持自由格式的查询参数.在参数编辑器中，以 JSON 对象格式输入参数名称和值，例如{ prop1":value1"，prop2":value2"；}.试试看"将它们作为 param=value 查询参数发送:

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:

但不确定是否支持 Codegen.

Not sure about Codegen support though.

这篇关于如何在 OpenAPI (Swagger) 中记录动态查询参数名称?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！