Spring Boot + Swagger + Redocで生成したAPIドキュメントをGitHub Pagesで公開する
はじめに
最近、REST API の仕様を他の開発チームに共有する方法を考える機会がありました。
その際、個人的に重要だと思ってることがいくつかあります。
- 標準化されたフォーマットであること
- ドキュメントがメンテナンスしやすいこと
- 関係者に素早く展開できること
- 視覚的な魅力があること
上記を満たす方法のひとつとして、Spring Boot + Swagger + Redoc で生成した API ドキュメントを GithubPages にて公開する方法を整理したので、その方法について書きます。
（Spring Boot + Swagger はよく見るし、詳しい説明は割愛します）
Spring Boot + Swagger でサンプル作る
デモ用に REST API のサンプルを用意しました。
API ドキュメントを生成する
Redoc を使って API ドキュメントを生成する方法を紹介します。
Swagger UI ではなく、あえて Redoc を利用するのは UIが綺麗で見やすい からです。
こんな感じのドキュメントが HTML で生成されます。
Redocly CLI のインストール
npm install -g @redocly/cli
Swagger JSON の生成
Spring Boot アプリケーションを起動し、以下のコマンドでSwaggerのJSONファイルを取得します。
curl http://localhost:8080/v3/api-docs -o ./docs/api-docs.json
API ドキュメントの生成
Redoc CLI を使用して、取得したSwagger JSONファイルからAPIドキュメントを生成します。
npx @redocly/cli build-docs ./docs/api-docs.json -o ./docs/index.html
GitHub Pages で API ドキュメントを公開する
今回は生成した API ドキュメントを GitHub Pages でホスティングします。
GitHub Pages の設定
リポジトリの Settings タブに移動し、左側にある Pages をクリックします。
Github Pages の設定ができる画面に遷移するので、Branch を指定して Save します。
公開されたドキュメントの確認
GitHub Pages の設定後、しばらくすると API ドキュメントが公開されます。
今回の例では、以下 URL にて公開されました。
（無料とはいえ、リソースがもったいない気持ちになるので暫くしたら消します）
さいごに
綺麗な API ドキュメントが手軽に公開できるとやる気出ますね。
Discussion