OpenAPI 入門 Part3 | オブジェクト定義を再利用

前回までのPart1,2では、リクエスト・レスポンスの基本的な定義の仕方を学んできました.
今回は、その定義をリファクタリングしていきます！

ざっくり結論

1. コンポーネントを作成
2. 各スキーマはコンポーネントを参照するようにする

Components Object

Components Objectは再利用可能なオブジェクトの定義です.
このオブジェクトは、OpenAPIファイルの中のさまざまな場所から参照できます.

↓サンプル

openapi.yaml

...
paths:
  /posts:
    get:
      responses:
        '200':
          description: post response
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Posts"
components:
  schemas:
    Posts:
      type: array
      items:
        $ref: "#/components/schemas/Post"
    Post:
      type: object
      properties:
        text:
          type: string
        imgSrc:
          type: string

/postsのGETリクエストのレスポンスを見てみます.
components/schemasの階層にPosts,Postを定義していますが、この階層構造は任意の名前です.

schemaやparameterに使う定義をこのように別で定義しておくと管理がしやすくなったり、再利用できたりします.

Reference Object

Reference Object は上の例で見たようにComponent Objectの位置を指定します.
上記の例では、Component Objectを同一ファイル内に定義していたので、#/componentsで呼び出していましたが、別ファイルにComponent Objectを定義しておくこともできます.

schema.yml

Posts:
  type: array
  items:
    $ref: "#/Post"
Post:
  type: object
  properties:
    text:
      type: string
    imgSrc:
      type: string

openapi.yml

...
paths:
  /posts:
    get:
      responses:
        '200':
          description: post response
          content:
            application/json:
              schema:
                $ref: "./schema.yml#/Posts"

同一階層にschema.ymlを作成した場合の例です.

このように、$refで相対パスを使ってschemaファイルに書いてあるComponent Objectにアクセスすることができます.

まとめ

今回は、Component Objectを使ってschema定義をリファクタリングする方法を解説しました.
インデントが深くなるとコードが追いにくくなるので、ぜひ活用したいです. また、再利用性の高そうなエラーの型をComponent Objectで定義できていると使い回すのにも便利ですね！