単一のエンドポイントの複数の投稿要求のOpen Apiドキュメント

Question

シングルエンドポイントAPIのSwagger/Open APIドキュメントを作成しようとしています。

私の単一のエンドポイントが

POSTのようになります。http://localhost/api/v1/process

ポスト本体は論理パスと応答スキーマ

Body1: {"jsonClass": "AnimalsRankedByLifeSpan"} Response1: schema-1

Body2: {"jsonClass": "AnimalsInRegion", "region":"Africa", "type":"lions"} Response2: schema-2

を決定

ドキュメントからの期待：各jsonClassは別々の呼び出しとしてリストされており、仕様を使用してすべてのjsonClassをサポートすることができます。

スガッガーはこのようなデザインをサポートしていません。もしそうなら、私に例を教えてください。

サポートされているjsonClassの種類ごとにリクエストレスポンスのドキュメントを提供するために使用できる他のApiドキュメントフレームワークはありますか？

Answer 1

OpenAPI 2.0と3.0には、同じ操作で異なる要求スキーマを異なる応答スキーマにマップする方法がありません。 Support an operation to have multiple specifications per path (e.g. multiple POST operation per path)

OpenAPI 3.0を使用している場合は、oneOfを使用して、要求と応答に複数の可能なスキーマを定義することができます。ただし、Body1がschema-1レスポンスを生成し、Body2がschema-2レスポンスを生成すると定義することはできません。操作descriptionでこれを口頭でのみ伝えることができます。

openapi: 3.0.0 
... 

paths: 
    /foo: 
    post: 
     requestBody: 
     required: true 
     content: 
      application/json: 
      schema: 
       oneOf: 
       - $ref: '#/components/schemas/Body1' 
       - $ref: '#/components/schemas/Body2' 
     responses: 
     '200': 
      description: OK 
      content: 
      application/json: 
       schema: 
       oneOf: 
        - $ref: '#/components/schemas/schema-1' 
        - $ref: '#/components/schemas/schema-2'