今更Swagger Spec + ReDoc + Firebase HostingでAPI仕様ページを作ったら劇的に捗った件について

# はじめに
REST APIを開発する際に、開発メンバとAPIの仕様に関して
恥ずかしながらこんな感じで共有していました。
<img width="560" alt="スクリーンショット 2019-02-15 14.54.01.png" src="https://qiita-image-store.s3.amazonaws.com/0/254318/135aaa59-eb4d-7296-49c0-1d96e8a9dcaa.png">

さすがにダルすぎる....と思い今更ですが

* Swagger Spec
* ReDoc
* Firebase Hosting

を使って、API仕様をWebブラウザで開発メンバに共有するようにしたので
そのやり方について書きます。

# TL;DR
* (当然だが)APIドキュメントを作ると捗るので、ちゃんと書こう
    * HTMLをホスティングして公開すると、常に全員が同じ仕様を見ることができるので良い。
        * Excelとかで仕様書渡しちゃうと、いろんなバージョンが各人のPCに出回るので...
* ReDocは導入が超簡単で、ページもおしゃれなのでオススメ
* Firebase Hostingを使ってできるだけ労力をかけずに公開すると捗る
    * 閲覧可能な接続元IPアドレス制限やベーシック認証などをかけましょう
* swagger.yamlの更新が少しダルい

急いでいる方は直接手順をご覧ください。
[手順](#手順)

# 各ツールの簡単な紹介
## Swagger Spec
![swagger.png](https://qiita-image-store.s3.amazonaws.com/0/254318/c8ce07ae-0499-9095-b200-ed692f533639.png)
Swagger Spec はRESTful APIを構築するためのオープンソースのフレームワーク「Swagger」の書式で記述した仕様書です。JSONもしくはYAML形式で記述します。

以下のようなAPI仕様を書くことで、以下のようなページの生成にも使えます。
![swaggereditor.png](https://qiita-image-store.s3.amazonaws.com/0/254318/8603c8da-5ada-01b7-5be5-b8d66ae0c348.png)


詳しくは以下を参照
[Swaggerの概要をまとめてみた。](https://qiita.com/gcyata/items/342073fa7607fd4082bd)

## ReDoc
<img width="500" alt="redoc-logo.png" src="https://qiita-image-store.s3.amazonaws.com/0/254318/4dfabda1-8055-3139-5280-772869277946.png">
API仕様を書いたswagger.yaml, swagger.jsonを読み込みHTMLページを生成する
APIドキュメンテーションツールです。

[Swagger UI](https://swagger.io/tools/swagger-ui/)でもHTMLは生成できますが

* 見た目がおしゃれ
* 多少のカスタマイズが可能

ということで、今回はReDocを採用しました。

HTML に redoc.min.js と swagger.yaml(or swagger.json) を読み込ませるだけ以下のようなページを生成できます。

<img width="800" alt="スクリーンショット 2019-02-15 15.14.47.png" src="https://qiita-image-store.s3.amazonaws.com/0/254318/1aa72042-522c-86d9-7661-c8a3134a2b71.png">


今風なデザインでヌルヌルと動きます。
![nested-demo.gif](https://qiita-image-store.s3.amazonaws.com/0/254318/a3c576d8-4a04-7284-7fcb-9a720e5de5bb.gif)
![code-samples-demo.gif](https://qiita-image-store.s3.amazonaws.com/0/254318/c28fa753-753c-920b-9d67-3a3173dde8cf.gif)

ReDoc GitHub ページ
https://github.com/Rebilly/ReDoc

参考
[Swagger Specから静的なHTMLを作るHTMLジェネレータを色々ためしてみた](https://qiita.com/buzztaiki/items/6b04d735f28e00b8b574)
[ReDoc - Angular な静的 Webページを生成できる REST API ドキュメンテーションツール](https://iktakahiro.hatenablog.com/entry/2017/06/09/090000)

## Firebase Hosting
<img width="400" alt="firebase-hosting.png" src="https://qiita-image-store.s3.amazonaws.com/0/254318/1b91bffd-78ea-ef9e-4f21-c5de77ed05c1.png">
Firebase Hostingは、Google が提供しているモバイルおよび Web アプリケーションのバックエンドサービス 「Firebase」の静的コンテンツホスティング機能です。
無料で利用でき、デフォルトでHTTPS対応されています。

# 手順
## 1. Firebase Hosting用プロジェクトの作成
Firebase Hostingに公開するプロジェクトを作成します。
今回はこのプロジェクト内でAPIドキュメントページを作成します。

手順の詳細は以下が参考になります。
[Firebase Hosting でWebサイトを公開する方法](https://qiita.com/gupuru/items/25a6722f6f802d3a5250)

## 2. Swagger Specを書く
開発しているREST APIの仕様をSwagger Specに書きます。
[Swagger Editor](http://editor.swagger.io/)
を使うのがおすすめです。

以下、サンプル。

```YAML:swagger.yaml
swagger: '2.0'

info:
  version: "1.0.0"
  title: sample swagger spec

paths:
  /posts/{id}:
    get:
      description: |
        description
        説明文

      parameters:
        -
          name: id
          in: path
          description: Id of array
          required: true
          type: number
          format: double

      responses:
        200:
          description: Successful responses
          schema:
            title: ArrayOfPosts
            type: array
            items:
              title: Posts
              type: object
              properties:
                name:
                  type: string
                title:
                  type: string
                content:
                  type: string
```

## 3. ReDocでAPIドキュメントページを生成する
ReDocを使って、swagger.yaml(or swagger.json)を元にAPIドキュメントページを生成します。

### 3-1. ReDocのインストール(CDNを利用する場合は不要)


```:yarnを使ってインストール
yarn add redoc
```

```:npmを使ってインストール
npm install redoc --save
```
### 3-2. redoc モジュールをHTMLから読み込む
Firebase Hostingに公開するAPIドキュメントページ(index.html)に以下を追加します。

CDN経由で読み込む場合

```html
<script src="https://cdn.jsdelivr.net/npm/redoc/bundles/redoc.standalone.js"> </script>
```

3-1.でインストールしたnode_modulesを読み込む場合

```html
<script src="./node_modules/redoc/bundles/redoc.standalone.js"> </script>
```

index.htmlの全体像は以下になります。


```html:index.html
<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc - sample API</title>
    <link rel="icon" href="./favicon.ico">
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>
  <body>
    <redoc spec-url="./spec/swagger.yaml"></redoc>
    <script src="./node_modules/redoc/bundles/redoc.standalone.js"></script>
  </body>
</html>
```
※上記以外に、favicon.icoを設定しています。

ディレクトリーツリーは以下。
<img width="243" alt="directory-tree.png" src="https://qiita-image-store.s3.amazonaws.com/0/254318/f0a0208e-9b95-7873-56d8-479042e290aa.png">

## 4. Firebase Hostingに公開する
`deploy`コマンドで公開します。

```
firebase deploy
```

成功するとURLが払い出されます。
アクセスすると、無事APIドキュメントがFirebase Hosting上で公開されていることが確認できます。
<img width="1269" alt="sample-api-doc.png" src="https://qiita-image-store.s3.amazonaws.com/0/254318/91940dba-d33f-19de-e58d-2877b7f325ba.png">

このまま放置するとインターネット上に公開されているので
URLを知っていると誰でもアクセスできてしまいます。

これが困る場合は

* 接続元のIPアドレスで制限する
    * 参考：[Firebase HostingにIPでアクセス制限をかける。そして少し妥協する。](https://qiita.com/otakky/items/1363e7b4c706dc9cd096)
* ベーシック認証をかける
    * 参考：[FirebaseでBasic認証をかけてサイトを作る(Hostingする)](https://qiita.com/567000/items/65f55eda8d7c6df09138)

などの対策を取ると良いです。


# まとめ
Swagger Spec + ReDoc　+ Firebase Hostingで簡単にAPIドキュメントページが公開できました。
APIドキュメントページを作ったことにより、API仕様に関するやり取りを
「このURL見て」
で大体済ませることができるので非常に楽になりましたｗ


ただ、Swagger Specの定義の更新がちょっとだるいのである程度自動化する術とかないか探しています。

**余談**

APIドキュメントページを公開するとメンバから喜ばれましたｗ
![result.png](https://qiita-image-store.s3.amazonaws.com/0/254318/4fd01563-e23d-5932-d984-91f7c5fae8c6.png)

---
最後までお読み頂きありがとうございました!
Twitterでも技術ネタやデザインについてなどもツイートしているので、よかったらフォローしてもらえると嬉しいです:stuck_out_tongue_closed_eyes:
→　[Twitter@jonghyo_](https://twitter.com/jonghyo_)