ReDoc+Vercelを利用して、高速でOpenAPIドキュメントを公開する

# ReDoc+Vercelを利用して、高速でOpenAPIドキュメントを公開する
## はじめに
ReDoc+Vercelを用いてOpenAPIドキュメントを高速で公開する方法です。
[ReDoc](https://github.com/Redocly/redoc)
[Vercel](https://vercel.com/)
[OpenAPI](https://www.openapis.org/)

今回の記事の作業内容は以下のリポジトリにコミットしています。
https://github.com/Cohey0727/redoc-sample

## 対象
以下の方を対象にしています。

- GitHubで作業をしたことがある
- OpenAPIでドキュメントを書いたことがある

Vercelの利用有無、ホスティングの知識は必要ありません。


## 実装
### ReDoc CLI
まずは初期準備です。yarnを用いてReDoc CLIが利用できるように準備します。
yarnではなく、npmを利用している方はyarnの部分をnpmに置き換えて読んでください。

```shell
mkdir redoc-sample
cd redoc-sample
yarn init
> question name (redoc-sample):
> question version (1.0.0):
> question description:
> question entry point (index.js):
> question repository url:
> question author:
> question license (MIT):
> question private:
> success Saved package.json
> Done in 9.65s.
yarn add redoc-cli -d
```

以下でうまくインストールできているか確認できます。

```shell
redoc-cli --version
> 0.10.3
```

### CLIを用いてビルド
OpenAPI準拠のyamlファイルまたは、jsonファイルを用意します。
今回は`spec.yaml`とします。またビルド成果物を`public/index.html`ファイルとして出力するものとします。

以下のコマンド実行します。

```shell
redoc-cli bundle spec.yaml -o public/index.html
```

成果物の確認

```shell
ls -1
> node_modules
> package.json
> public
> spec.yaml
> yarn.lock
cd public
ls -1
> index.html
```

`public/index.html`が出力されています。このファイルをChrome等ブラウザで開くと以下のように表示されていれば成功です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/235240/8f836ccb-2b61-a5c9-3671-e2a34cdb6e3c.png)

`package.json`に`scripts`のブロックを追記してビルドコマンドを簡略化しておきます。

```package.json
{
  "name": "redoc-sample",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "scripts": {
    "build": "redoc-cli bundle spec.yaml -o public/index.html"
  },
  "dependencies": {
    "redoc-cli": "^0.10.3"
  }
}

```
## デプロイ
### GitHub準備
GitHubより、Vercelと連携するGitRepositoryを作成します。
ここではリポジトリURLをhttps://github.com/Cohey0727/redoc-sample.git とします。


以下のコマンドで作業ディレクトリをgit管理します。
また`.gitignore`ファイルを追加して`node_modules`と`public`フォルダを追記します。

```shell
git init
touch .gitignore
echo node_modules/ >> .gitignore
echo public/ >> .gitignore
git add .
git commit -m 'Initial Commit'
git remote add origin https://github.com/Cohey0727/redoc-sample.git
git push -u origin master
```

### Vercelデプロイ
Vercelのダッシュボード画面より、`New Project`を押下します。
![ダウンロード (1).png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/235240/350a3903-070c-2d44-662f-4b4faaee8ff0.png)


GitHubの認証をしたのち、先程作成したリポジトリを選択します。
![ダウンロード.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/235240/486f8cde-ff66-1894-d4d0-83e107b1fef0.png)

プロジェクトはrootディレクトリなのでそのまま`Continue`を押下します。
![Screenshot from 2021-02-06 17-14-26.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/235240/f8d723df-e729-5ebe-7091-bf1e2d5d71c6.png)

 以下の項目を埋めて、`Deployを押下します。`

|項目|値|
|---|---|
|FRAMEWORK PRESET|Other|
|ROOT DIRECTORY|./|
|BUILD COMMAND|yarn run build|
|OUTPUT DIRECTORY|public|

![Screenshot from 2021-02-06 17-14-43.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/235240/edf68ae5-c4aa-afa6-68dc-7d8492e36778.png)

ビルドが成功すると以下の画面に飛ばされます。
![Screenshot from 2021-02-06 17-16-45.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/235240/4d247544-4f22-cb6a-bfd2-01371090c724.png)

`Visit`を押下してサイトがうまく構成されているかを確認します。
![Screenshot from 2021-02-06 17-16-52.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/235240/a5d79bdd-4031-b8c3-fe76-586a501136a3.png)

### 更新
Vercelはデフォルトでgitにコミットがあると自動でリビルドしてくれます。
yamlファイルを更新してコミットすると自動で反映されます。

## まとめ
オプションでテンプレートやテーマを変更することもできるようです。
外部公開APIのドキュメント作成の選択肢になればいいなと思います。