web-dev-qa-db-ja.com

OpenAPI（Swagger）で動的クエリパラメーター名をドキュメント化する方法

次のクエリを文書化する方法はありますか？

GET api/v1/users?name1=value1&name2=value

クエリパラメータ名は動的であり、クライアントから受信されます。

最新のSwagger APIを使用しています。

swaggerswagger-editorswagger-codegenopenapi
11
Sharad Ahire

自由形式のクエリパラメータはOpenAPI 3.0を使用して記述できますが、OpenAPI 2.0（Swagger 2.0）は使用できません。パラメータには、シリアル化メソッドtype: objectおよびstyle: formを含むexplode: trueが必要です。オブジェクトは?prop1=value1&prop2=value2&...としてシリアル化され、個々のprop = valueペアはオブジェクトプロパティです。

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 in Swagger UI

Codegenのサポートについては不明です。

16
Helen

@Helenの答えは、 springdoc-openapi-ui ライブラリを使用したSpringでも完全に機能します。

依存：

 <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.1.43</version>
 </dependency>

API関数で、次のパラメーターを追加します。

 @Parameter(in=ParameterIn.QUERY,
            name="params", style=ParameterStyle.FORM,
            schema=@Schema(type="object"), explode=Explode.TRUE,
            example="") String paramsObj
2
Nischal Revooru