【Swagger3.0】１つのステータスコードに対して複数のレスポンスを定義 (oneOf)

状況

Swaggerで、とあるapiのレスポンスにおいて、「同じステータスコードを返すんだけれど、bodyの内容が違う場合がある」時、SwaggerのoneOfという書き方で対応できます。(swagger3.0以上だったはず)

例

openapi: 3.0.0
...
省略
...
paths:
  /hello:
    get:
      tags:
        - hellos
      description: ハローが帰ってくるapiです。
      responses:
        '200':
          description: 登録されている支払い方法が返される。
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/responses/HelloResponse1'
                  - $ref: "#/components/responses/HelloResponse2"
              examples:
                response1:
                  summary: HelloResponse1の通常レスポンスです
                  value:
                    success1:
                      message_title: Response1
                      message: ハロー１のレスポンスのexampleです
                response2:
                  summary: HelloResponseの特別なレスポンスです
                  value:
                    success1:
                      message_title: Response２
                      message: ハロー２のレスポンスのexampleです
components:
  responses:
    HelloResponse1:
      type: object
      properties:
        success1:
          type: object
          properties:
            msg_title:
              type: string
              example: HelloResponse1
            message:
              type: string
              example: ハロー１のレスポンスです。
    HelloResponse2:
      type: object
      properties:
        success1:
          type: object
          properties:
            msg_title:
              type: string
              example: HelloResponse2
            message:
              type: string
              example: ハロー２のレスポンスです。

画面ではこう表示されます。


examplesを定義したことにより、別のレスポンスを表示できるようになっています。




Schemaを選択すれば、oneOfを使用して定義した部分を見ることができます。


あとはいい感じで定義してあげてください。レアケースかもしれませんが、意外と役立つと思います。