Open1

swaggerでxxxOfにexampleをつけたい時に見る記事

ふじしろふじしろ

xxxOfについて

exampleを使う場合

examplesを使う場合

responses:
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                # oneOf, anyOf, allOfのいずれか
                xxxOf:
                  - $ref: '<レスポンス1>'
                  - $ref: '<レスポンス2>'
                  - ...
              # xxxOf内に定義した順序に合わせてexamplesを記述する
              examples:
                  <レスポンス1に対応する名称>:
                      value:
                          <レスポンス1のプロパティ1>: <exampleとして表示したい値>
                          <レスポンス1のプロパティ2>: <exampleとして表示したい値>
                          ...
                  <レスポンス2に対応する名称>:
                      value:
                          <レスポンス2のプロパティ1>: <exampleとして表示したい値>
                          ...
                  ...

以下具体例サンプル

openapi: 3.0.0
# 〜略〜
    put:
      tags:
        - hoge
      description: ステータスコード400に対し、エラーの種類に応じて複数のレスポンスを定義
      parameters:
        - name: id
          in: path
          description: ほげID
          required: true
          schema:
            $ref: '#/components/schemas/Hoge/properties/id'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/requestBodies'
        required: true
      responses:
       # 〜略(他のステータスコードなど)〜
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/responses/InvalidFormat'
                  - $ref: '#/components/responses/DuplicatedTitle'
                  - $ref: '#/components/responses/MethodArgumentNotValid'
              examples:
                InvalidFormat:
                  value:
                    status: 400
                    message: 無効な入力値です。
                DuplicatedTitle:
                  value:
                    status: 400
                    message: すでに登録済みです。
                MethodArgumentNotValid:
                  value:
                    status: 400
                    message: バリデーションエラーです。

参考:【Swagger3.0】1つのステータスコードに対して複数のレスポンスを定義 (oneOf) - 196Log