OpenAPIでレスポンスボディに配列を使用する

はじめに

OpenAPIに関しての記事が少ない気がする、もしくは僕の検索の仕方が下手なのかわかりませんが、とにかくここにまとめておきます。
間違っていたりしましたらぜひご指摘いただけると嬉しいです。

ちなみに、openAPIのバージョンとしては、3.0.3を使用。

OpenAPIで配列を使用する

ここでは、レスポンスの部分に関しては別ファイルに分割している。postでのレスポンスに関しては、postResponse.yamlというファイルに分割し、そこにレスポンスの内容を記述している。以下が例です。

postResponse.yaml

description: OK
content:
  application/json:
    schema:
      oneOf:
        - type: object
          properties: {}
        - type: object
          properties:
            goriras:
              type: array ## ここtypeをarrayとすること
              items:
                type: object
                description: ゴリラ一覧
                properties:
                  age:
                    type: integer
                    description: 年齢
                    required: true
                  name:
                    type: string
                    description: 名前
                    required: true
    examples:
      ゴリラあり:
        value:
          {
            goriras:
              [
                { age: 2, name: takeshi },
                { age: 23, name: hage },
              ], ## ここのカンマを忘れるとexamplesとしてSwagger Previewで正常に表示されない
          }
      ゴリラなし:
        value: {}

Swagger Previewの表示はどうなるか

ゴリラあり

こんな感じで、ゴリラありの場合は配列でレスポンスの値があるのが表現できる。

ゴリラなし

ゴリラなしの場合はこのように何もレスポンスがないことを表現することができる。

おわり

書き方だけで詰まる人はたくさんいると思うからここに記しておきます。
詳しいことは自分でググってください。