web-dev-qa-db-ja.com

Swagger;オプションのパラメーターに基づいて同じコードで2つの応答を指定する

この質問は（ Swagger-オプションのオブジェクトプロパティまたは複数の応答を指定 ）の複製ではありません。OPが200または400を返そうとしたためです。

オプションのパラメーターを持つGETがあります。例：GET /endpoint?selector=foo。

パラメーターが渡されたかどうかに基づいてスキーマが異なる200を返します。たとえば：

GET /endpoint -> {200, schema_1}
GET /endpoint?selector=blah  -> {200, schema_2}

Yamlでは、2つの200コードを試しましたが、ビューアは1つだけを指定したかのようにそれらを押しつぶしました。

これを行う方法はありますか？

編集：以下は関連しているようです： https://github.com/OAI/OpenAPI-Specification/issues/27

swaggerswagger-2.0
25
Tommy

OpenAPI 3.0では、oneOfを使用して、同じ操作に対して複数の可能なリクエストボディまたはレスポンスボディを定義できます。

openapi: 3.0.0
...
paths:
  /path:
    get:
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'

ただし、特定の応答スキーマを特定のパラメーター値にマップすることはできません。これらの詳細を応答、操作、および/のdescriptionに口頭で文書化する必要があります。またはパラメータ。

関連する機能強化のリクエストは次のとおりです。
get- ^ post- ^などによるoperationObjectのオーバーロードを許可


Swagger UIユーザーへの注意：この記事の執筆時点（2018年12月）Swagger UIはoneOfおよびanyOfの例を自動的に生成しませんスキーマ。 この問題 をフォローして更新することができます。

回避策として、応答exampleまたはexamplesを手動で指定できます。複数のexamplesを使用するには、Swagger UI 3.23.0+またはSwagger Editor 3.6.31+が必要です。

      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ResponseOne'
                  - $ref: '#/components/schemas/ResponseTwo'
              example:   # <--------
                foo: bar
14
Helen

私は同じものが欲しかったので、うまくいくと思われる回避策を思いつきました：

2つの異なるパスを定義しました。

/path:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseOne'
(...)

/path?parameter=value:
(...)
      responses:
        200:
          description: Sucesso
          schema:
            $ref: '#/definitions/ResponseTwo'
(...)

パスはswaggerエディターで機能します。各オプションを別々に文書化し、2番目のケースのみに存在する可能性のあるオプションパラメータを追加して、APIドキュメントをよりクリーンにすることもできます。 operationIdを使用して、生成されたAPIメソッドのクリーンな名前を生成できます。

ここに同じ解決策を投稿しました（ https://github.com/OAI/OpenAPI-Specification/issues/27 ）。これ以上何かが足りないかどうかを確認します。

私はそれがそれを行うことを明示的に許可/奨励されていないことを理解しています（明示的にそれを禁止している場所も見つかりませんでした）。しかし、回避策として、現在の仕様でこの動作を使用してAPIを文書化する唯一の方法であるため、オプションのように見えます。

私が見つけた2つの問題：

  • Javaコード生成URLは「=」記号をエスケープするため、生成されたコードでこれを修正しない限り機能しません。おそらく他のコードジェネレーターで発生します。
  • クエリパラメータがさらにある場合は、追加の「？」が追加されます。そして失敗する。

それらがブロッカーでない場合、少なくともそのようなケースを適切に文書化し、swaggerエディターでテストできるようになります。

2
CristianTM