ことさら−古都プログラマーの更級日記

京都でお寺を回りながら御朱印集めをしていたり、LoLをしたり試合を見に行ったりしているエンジニアのブログです。技術的なはなしとか日常的なはなし、カメラやLoLや競馬の話も書きます。右メニューに検索やらカテゴリーやらがあるので、見たい記事だけ見てね!

Swagger-UI(OpenAPI 3.0 )のドキュメントをGitHubで管理しつつ、pushやマージをしたらドキュメントが更新されるような運用方法

もくじ

SwaggerをGitHubで管理したい

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

  1. 使い慣れている
  2. 変更点のレビューが出せる
  3. ソースコードとドキュメントを同じリポジトリで管理しておくことで、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のように公開されるみたいなので、この機能を使います。

  1. docsディレクトリを作成し
  2. swagger-ui のリポジトリをcloneしてきて *1
  3. 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 を開くと手元でもドキュメントの確認ができます。

GitHubにPushして確認

さて、これで一通り揃ったのでmasterにcommitしてpushします。

pushしたら、リポジトリのSettingsでGitHub PagesのSourceをmaster branch /docs folderを設定します。 これをするとdocsリポジトリ以下がGitHub Pagesとして公開されます。

f:id:yoshiki_utakata:20180419173122p:plain

しばらく待っていると Your site is published at http://yoshikyoto.github.io/lgtmoon/ などと表示されるようになりドキュメントが閲覧できるようになります。

まとめ

多分一番簡単なdocumentをGitHubで管理してGitHub Pagesで公開する方法ですが、ブランチ毎に確認する、のようなことは出来ません。とりあえずmasterブランチのドキュメントを確認することができます。

参考

tech.recruit-mp.co.jp

Web API: The Good Parts

Web API: The Good Parts

*1:cloneにまあまあ時間がかかります