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

はじめに

ReDoc+Vercelを用いてOpenAPIドキュメントを高速で公開する方法です。
ReDoc
Vercel
OpenAPI

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

対象

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

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

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

実装

ReDoc CLI

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

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

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

redoc-cli --version
> 0.10.3

CLIを用いてビルド

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

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

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

成果物の確認

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

public/index.htmlが出力されています。このファイルをChrome等ブラウザで開くと以下のように表示されていれば成功です。

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フォルダを追記します。

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を押下します。

GitHubの認証をしたのち、先程作成したリポジトリを選択します。

プロジェクトはrootディレクトリなのでそのままContinueを押下します。

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

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

ビルドが成功すると以下の画面に飛ばされます。

Visitを押下してサイトがうまく構成されているかを確認します。

更新

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

まとめ

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