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

## まえおき

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だけで動かせる。


```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>
```

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

```html
    <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](https://github.com/heroku/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のドキュメントを見れるようになる。

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

<img width="1514" alt="貼り付けた画像_2018_07_02_0_49.png" src="https://qiita-image-store.s3.amazonaws.com/0/74571/fc62cee5-bc3b-12b4-492c-1e5fab4139d6.png">

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

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

```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 //←これを追加
  ],
```

こうすることで

![image.png](https://qiita-image-store.s3.amazonaws.com/0/74571/b3cac713-e00d-b8db-3fbb-e11d9bae6397.png)

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

## 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 に今回のお試し内容を置いてみました。