✒️

[Swagger]responseBodyの例をスキーマ定義のサンプル値を用いつつ複数定義したかった

2022/07/01に公開

概要

SwaggerではメソッドのresponseBodyの例をexamplesで複数定義することができて、リソースが１つも見つからない場合のresponseBodyも例として定義しておきたい場合などに便利です。
しかし、componentsで定義したスキーマ定義のpropertiesのexample値を利用しつつ、複数responseBody定義する方法がパッと出てこなかったので、個人メモとして記載します。

結論

examples内で愚直に$refでスキーマ定義参照したらできました。

responses箇所抜粋

      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                $ref: "#/components/schemas/UserList"
              examples:
                users:
                  $ref: "#/components/schemas/UserList"
                noUser:
                  value: []

サンプル定義ファイル全体

openapi.yml

openapi: 3.0.3
info:
  title: Test API
  version: 1.0.0
paths:
  /users:
    get:
      tags:
        - users
      summary: Returns a list of user infomation
      description: Returns a list of user infomation
      responses:
        "200":
          description: Success
          content:
            application/json:
              schema:
                type: array
                $ref: "#/components/schemas/UserList"
              examples:
                users:
                  $ref: "#/components/schemas/UserList"
                noUser:
                  value: []
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
          example: 1
          readOnly: true
        name:
          type: string
          example: Dave
    UserList:
      type: array
      items:
        type: object
        $ref: "#/components/schemas/User"

問題点

問題点として1つあるのが、$refしているexampleにsummaryを書いてもプレビューに反映されないことでしょうか。

              examples:
                users:
                  summary: A list of user infomation  # プレビューに反映されない
                  $ref: "#/components/schemas/UserList"
                noUser:
                  value: []

他にも良い方法があれば、是非教えていただけると嬉しいです！

概要

結論

問題点

Discussion