OpenAPI定義ファイルを分割管理 & 見やすいAPI定義書の運用をはじめました
目次
はじめに
お久しぶりです。にこにこぷん世代のなかむらです。
今月、30歳前後のカメが３匹、我が家に仲間入りしたのですが、名前がなかったようなので「じゃじゃまる」「ぴっころ」「ぽろり」と名付けました。
最近はずーっとConfit2023に向けてConfit大会Webサイトサービスのリニューアルプロジェクトを担当しています。今回は進行中のプロジェクトでちょっぴり改善したAPI定義書の取り組みについて紹介しようと思います。
これまでのAPI定義書の課題
アトラスのAPI定義書は、スプレッドシートタイプとOpenAPI（REST API記述フォーマット）定義ファイルタイプが存在しています。
スプレッドシートは
- 更新が簡単
- フォーマットや記述の自由度が高く、補足コメントなども書きやすい
という利点がありますが、
- プロジェクトや作成者によってフォーマットがバラバラになりがち
- 更新履歴を残すのが面倒
という欠点があります。
OpenAPI定義ファイルはYAMLファイルに記述するので
- フォーマットが統一される
- Gitでソースコードと同様にバージョン管理ができ、更新履歴の管理が簡単
という利点がありますが、
- 統合開発環境やブラウザの拡張機能などを利用しないと Swagger-UIのHTML形式のAPI定義書が確認できない（※ SwaggerとはOpenAPI仕様にもとづいて構築されたオープンソースツールセットであり、APIの設計、作成、文書化に役立つフレームワークで、Swagger-UIはSwaggerの主なツールのひとつです。)
- 拡張機能でHTML形式のAPI定義書を確認するために、たくさんのAPI定義をひとつのファイルにまとめて記述していて行数が多くなり、参照するのも更新するのも大変
という課題が残りました。
管理しやすく、見やすくするを目指す
課題を解消すべく、取り組みのゴールは以下に設定しました。
- OpenAPI仕様を継続してフォーマットを固定する
- ファイルを分割して、URL毎、要素毎のファイルで管理する
- 見やすいHTMLのAPI定義書を出力して、いつでも誰でもブラウザで確認できるようにする
ファイルを分割して管理する
現在のディレクトリ構成は以下のようになりました。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 |
root ├── apis.yml │ ├── components │ ├── index.yml │ ├── parameters.yml │ ├── properties │ │ ├── A.yml │ │ └── parts │ │ └── A-parts.yml │ ├── responses.yml │ └── schemas.yml │ └──paths ├── role │ └── A.yml └── index.yml |
大元の親ファイル(apis.yml）では、構成要素ごとにファイルを 「$ref」による相対パスで参照するように変更しました。
|
1 2 3 4 |
paths: $ref: './paths/index.yml' components: $ref: './components/index.yml' |
URLについては一覧性が高い方が良いので、paths/index.html で全てを記述するようにしています。他の構成要素については各ディレクトリを作成してURLごとに定義ファイルを管理するようにしました。
ファイルを分割したことで記述している途中の状態を統合開発環境などでリアルタイムに確認することができなくなりましたが、これまではパラメータやレスポンスで同じ定義を繰り返し書いていたので、ファイルを細かく分割することで重複定義もしなくなり、効率よく作成、編集できるようになりました。
ファイルを結合してHTML化する
OpenAPI定義ファイルは最終的には1つのJSONやYAMLのファイルとして結合されることが想定されているので、HTML形式に変換するには分割管理しているファイルを結合する必要があります。
そこでローカルの統合開発環境でもCI/CDツール上でも容易に実行できるように swagger-merger というnpmライブラリを利用して、複数のOpenAPI定義ファイルを結合することにしました。
swagger-mergerで作成した統合定義ファイルのHTML変換には、Redocを利用することにしました。Swagger Codegenで生成するものより綺麗で見やすいHTMLを生成できるからです。
以下はReDoc Interactive Demoのキャプチャですが、OpenAPI定義ファイルをRedocで変換したHTMLと同じ見た目です。
生成したAPI定義のHTMLファイルはテスト環境のデプロイ時に更新するようにCI/CDツールで設定して、マージされた最新の状態がいつでもブラウザで参照できるようにしました。
取り組み内容のフィードバック
プロジェクトメンバーから取り組みについて以下のような意見をもらいました。
良かった点
- YAMLの定義ファイルを直接見るよりHTML化したことで確認しやすい
- API定義書を見れば更新状態がすぐ分かる
- プロジェクトごとに異なるフォーマットでなく、OpenAPI仕様で統一され、見慣れたフォーマットで管理できる
Chrome拡張機能でブラウザからAPI実行できてすぐ挙動が確認できる
悪かった点
- 分割するとAPI定義の全体像が掴みにくい
- 小さな更新もPR経由なのが面倒くさい
- 補足のメモが書きにくい
まだ多少の難はあれど、API定義書の運用コストや定義を参照するときのメンバーのストレス軽減ができたかなと思います。
さいごに
API定義書のフォーマットを統一していつでも誰でも確認できるようにできたので、フロントエンドとバックエンドで担当が分かれているConfitの開発チームでは生産性向上や効率化に繋がり、これからもじわじわと取り組みの効果が期待できるのではないかと考えています。
まだまだAPI定義書については課題や展望もあるので、これからも自分たちのやり方のアップデートを続けることでチームのパフォーマンス向上を目指していきたいと思います。
