SwaggerをGitHubで管理したい
やりたいことまとめ
どう実現するか
導入方法
- OpenAPI 3.0 Specificationのファイルをdocs以下に置く
- GitHubにPushして確認
まとめ
参考

SwaggerをGitHubで管理したい

SwaggerをGitHub(Git)で管理したい場合があるかと思います。

使い慣れている
変更点のレビューが出せる
ソースコードとドキュメントを同じリポジトリで管理しておくことで、APIの仕様が変わった時にドキュメントの変更をし忘れる、ということが減る

ただ、SwaggerをGitHubで管理することにに関してなかなか知見を得られませんでした。Swagger Editorを使って編集してzipをダウンロード、などはよく見る記事なのですが、そうではなくて、GitHubでドキュメントを管理してmasterにマージだれたら自動でドキュメントがビルドされる みたいなことがしたいわけです。

やりたいことまとめ

OpenAPI 3.0 の仕様に則って書いたyamlをGitで管理したい
masterブランチが更新されたらCIが動いてドキュメントをビルドして公開して欲しい

できればやりたいけど今回は一旦考えないこと

yamlの差分レビューだとよくわからないので、整形後のドキュメントで比較したい
OpenAPI 3.0 の yaml を元にCIが回ってドキュメントと実装が合っているかをある程度自動で確認したい

どう実現するか

大きく分けて2つあると思います

Swagger UI を使う
bootprint-swagger のような、yamlからHTMLを生成するツールを使ってCIで回す

今回は簡単な Swagger UI で行こうかとおもいます。

導入方法

https://github.com/swagger-api/swagger-ui のdist以下のファイルを使った実現方法です。

まず、ドキュメントを置きたいリポジトリのdocsディレクトリ以下にドキュメントを置きます。これは極論なんでも良いのですが、GitHubのリポジトリのルートにdocsを置くとGitHub Pagesのように公開されるみたいなので、この機能を使います。

docsディレクトリを作成し
swagger-ui のリポジトリをcloneしてきて *1
swagger-uiのdistディレクトリの中身をdocsディレクトリに移動します。

$ mkdir docs
$ git clone git@github.com:swagger-api/swagger-ui.git
$ cp swagger-ui/dist/* docs
$ ls docs
favicon-16x16.png                    index.html                           swagger-ui-bundle.js                 swagger-ui-standalone-preset.js      swagger-ui.css                       swagger-ui.js
favicon-32x32.png                    oauth2-redirect.html                 swagger-ui-bundle.js.map             swagger-ui-standalone-preset.js.map  swagger-ui.css.map                   swagger-ui.js.map

こういう感じになるかと思います。

OpenAPI 3.0 Specificationのファイルをdocs以下に置く

今回は docs/specs/index.yml を作成し、そこに仕様を書くことにしました。

$ mkdir docs/specs
# docs/specs/index.yml を作成・編集
# なんやかんや編集

そしたら docs/index.html の中身を少し修正します。

# docs/index.htmlを編集
$ git diff
diff --git a/docs/index.html b/docs/index.html
index 7a45f1d..fdf588a 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -41,7 +41,7 @@

       // Build a system
       const ui = SwaggerUIBundle({
-        url: "http://petstore.swagger.io/v2/swagger.json",
+        url: "specs/index.yml",
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [

この状態で docs/index.html を開くと手元でもドキュメントの確認ができます。