swagger-ui + heroku-review-appsでAPIドキュメントを誰でも見れる＆レビューできる状態にする #swagger

まえおき

Swaggerで書いたAPIドキュメントをGitHub flowでメンテしていくときに、どうしたらいいかなーと考えた話。
Pull Request時点でheroku-review-appsのプレビュー環境が自動的に立ち上がってswagger-ui見れたら、だいぶレビューしやすくなりそうですよね。

ということで、

API作る人が、Swagger Editorでドキュメント書いて、swagger.ymlに反映する
Pull Requestでは、レビューワーはymlではなく、HTMLのAPIドキュメントでレビューしたい！

くらいを要件に考えてみた＆やってみた。

swagger-uiを最小構成で動かすには？

いろいろなQiita記事で書かれているように、swagger-uiは
https://github.com/swagger-api/swagger-ui/blob/master/dist/
配下をまるっとコピーすれば、Nodeがない環境でも動く。

もっというと、Faviconが要らないなら、CDNを利用することで、index.htmlだけで動かせる。

    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >

    <script src="./swagger-ui-bundle.js"> </script>
    <script src="./swagger-ui-standalone-preset.js"> </script>

のところを↓のように書き換えればいいだけだ。

    <link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui.css" >

    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui-bundle.js"> </script>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.17.2/swagger-ui-standalone-preset.js"> </script>

heroku-buildpack-static を使ってHerokuでホストする

index.htmlだけで動作するので、heroku-buildpack-nodeとか使うまでもなく、heroku-buildpack-staticでホストできる。

index.html内の `url` 書き換え

デフォルトのURLが https://petstore.swagger.io/v2/swagger.json になっているので、そこは /swagger.yml (https://xxxxx.herokuapp.com/ は付けなくてもよさそう)に書き換えておこう。

index.html

      // Build a system
      const ui = SwaggerUIBundle({
        url: "https://petstore.swagger.io/v2/swagger.json", //←ここを"/swagger.yml"に書き換える
        dom_id: '#swagger-ui',

ファイルの配置と、static.jsonの用意

swagger.yml
static.json
dist/
  |- index.html

こんな感じのディレクトリ構造で、static.jsonというファイルを以下の内容で用意する。

static.json

{
  "root": "dist/",
  "routes": {
    "/swagger.yml": "../swagger.yml"
  }
}

dist/ をルートディレクトリにしているので、 swagger.ymlを1階層上にたどらないといけないらしい。

とりあえずデプロイしてみる

ここまでやれば、

$ heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static -a アプリ名
$ git push heroku master

で、手動デプロイすれば、swagger-uiのドキュメントを見れるようになる。

ヘッダーが邪魔なので消す

https://github.com/swagger-api/swagger-ui/wiki/FAQ#how-to-hide-topbar にやり方が書いてあった。

index.html の中に書いてあるJSを少し修正する

// https://github.com/swagger-api/swagger-ui/wiki/FAQ#how-to-hide-topbarにあるように定義
function HideTopbarPlugin() {
  // this plugin overrides the Topbar component to return nothing
  return {
    components: {
      Topbar: function() { return null }
    }
  }
}


SwaggerUIBundle({
  url: "http://petstore.swagger.io/v2/swagger.json",
  dom_id: '#swagger-ui',
  presets: [
    SwaggerUIBundle.presets.apis,
    SwaggerUIStandalonePreset
  ],
  plugins: [
    SwaggerUIBundle.plugins.DownloadUrl,
    HideTopbarPlugin //←これを追加
  ],

こうすることで

こんな感じで、スッキリなくなってくれる。

heroku-review-appsを設定する

https://qiita.com/kon_yu/items/6d2c0ae91d0176ceb167#rewviewapps%E3%81%AE%E8%A8%AD%E5%AE%9A%E3%81%99%E3%82%8B あたりを参考に、Herokuのコンソールでポチポチやればいける。

まとめ

Pull Request時点でプレビュー環境が自動的に立ち上がって、swagger-ui触れると、やっぱりだいぶレビューしやすくなりそうです。

https://github.com/YusukeIwaki/openapi300playground に今回のお試し内容を置いてみました。

swagger-ui + heroku-review-appsでAPIドキュメントを誰でも見れる＆レビューできる状態にする