如何在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.0来描述自由格式的查询参数，但不能使用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.0, but not OpenAPI 2.0 (Swagger 2.0). The parameter should have type: object with the serialization method style: form and explode: true. The object will 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屋！