OpenAPI 定義ファイル分割のすゝめ
OpenAPIとは
RESTfulなWebサービスを記述、生成、利用、可視化するためのインターフェースファイルの仕様です。 以前はSwaggerフレームワークの一部でしたが、2016年にOpenAPI Initiativeが統括する独立プロジェクトとなりました。 Swaggerや他のいくつかのツールは、インターフェースファイルを指定してコード、ドキュメント、テストケースを生成することが可能です。
OpenAPIの正確な仕様については、↓から確認できます。 https://swagger.io/specification/
プロジェクトでの利用法
プレセナの一部プロジェクトでは、API定義をOpenAPI仕様に従って記述するだけでなく、定義ファイル(openapi.yaml)からコードを自動生成して利用しています。
OpenAPI定義ファイルの分割
肥大化するopenapi.yaml
当初はAPI定義ファイルであるopenapi.yamlの1ファイルに全ての記述をしていました。 結果として、下記のような問題が発生しました。
ファイルサイズの増加(約2500行)
コンフリクトの頻発
編集すべき記述を素早く見つけられない
これらの問題に対処するためにopenapi.yamlの分割をおこなうことにしました。
openapi.yamlファイルの構成
openapi.yamlのファイルは大きく分けると下の様なブロックに分かれています。
バージョン情報といったメタ情報:info、serversなど
エンドポイントのURLやリクエスト/レスポンス情報:paths
再利用可能なオブジェクト情報:components
主に記述量が肥大化してしまうのは pathsとcomponentsであったため、これらを別ファイルに分割しました。
ファイルの分割
ファイルの分割は簡単です。
定義内の他コンポーネントを参照できるようにするフィールドである$ref
を相対パスで記述するだけです。
openapi.yaml
/paths/pet.yaml
/schemas/Pet.yaml
フォルダ構造
openapi.yamlをルートファイルとして、同階層にpathとschemasのフォルダを作成しました。
paths配下のファイルの命名規則としては、シンプルにエンドポイントURLの「/」を「_」にするファイル名としました。
/paths/pet/find-by-status.yaml
のように階層を深くするアイデアもあったのですが、schemasへの参照を$ref
で記述する際、"../../schemas/Foo"
, "../../../schemas/Bar"
のように 「..」を書く回数の混乱が生じないように現在のような命名規則をとりました。
エンドポイントURLにidが含まれる場合(ex. /pet/{petId}/upload-image)、理想的にはpet_[petId]_upload-image.yaml
のようにしたかったのですが、「[]」を含むと自動生成コードで問題が生じたため、シンプルにpet_petId_upload-image.yaml
としました。
まとめ
分割によって見通しがよく開発をすすめることができるようになりました。
Visual Studio Codeで開発しているなら、この拡張をいれることで$ref
の記述からファイル参照もできるのでおすすめです。
https://marketplace.visualstudio.com/items?itemName=42Crunch.vscode-openapi
しばらくこれで開発を進めてみて、課題感がまた出てきたらブラッシュアップしていきたいと思います。
最終更新