【要約】Redocly + Dockerで複数のOpenAPI YAMLを1つのドキュメントポータルに統合した話 [Qiita_Trend] | Summary by TechDistill
> Source: Qiita_Trend
Execute Primary Source
// Problem
バックエンド開発チームが、マイクロサービス化に伴い増大するOpenAPI定義の管理と閲覧に苦慮した。
- ・閲覧ツールがSwaggerやVS Code拡張など、メンバー間でバラバラであった。
- ・「どのAPIをどこで確認すべきか」という問い合わせが頻発した。
- ・OpenAPIの仕様違反を事前に検知する仕組みが欠如していた。
// Approach
開発者が一箇所で全APIを確認できるよう、RedoclyとDockerを用いた統合ポータルを構築した。
- ・Redoclyを使用して、OpenAPI YAMLからHTMLドキュメントを生成した。
- ・Pythonスクリプトにより、複数ファイルを一括でHTML化する仕組みを導入した。
- ・Docker Composeを用い、Node.jsやPythonの環境構築を不要にした。
- ・キャッシュ問題を避けるため、独自のNo-cacheサーバーを実装した。
// Result
開発チームが、APIドキュメントの閲覧と品質管理を効率化することに成功した。
- ・全APIをサイドバーから選択できる、統一されたポータルを実現した。
- ・
docker compose upの実行のみで、即座に閲覧環境が整うようになった。 - ・
redocly lintにより、コミット前の仕様違反検知が可能になった。
Senior Engineer Insight
> 本構成は、マイクロサービス環境におけるドキュメント管理の標準的な解だ。Redoclyの採用は、Lintと生成を単一ツールで行えるため運用コストが低い。Dockerによる環境の抽象化は、開発者間の環境差異を排除する優れた判断だ。ただし、ポータルのサイドバー更新が手動である点は、API増大時に課題となる。CI/CDと連携し、YAMLの追加を検知してポータルを自動更新する仕組みへの拡張を推奨する。