ReDoc+Vercelを利用して、高速でOpenAPIドキュメントを公開する
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
のブロックを追記してビルドコマンドを簡略化しておきます。
{
"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のドキュメント作成の選択肢になればいいなと思います。
Author And Source
この問題について(ReDoc+Vercelを利用して、高速でOpenAPIドキュメントを公開する), 我々は、より多くの情報をここで見つけました https://qiita.com/cohey0727/items/0162b9ac8901ca227f15著者帰属:元の著者の情報は、元のURLに含まれています。著作権は原作者に属する。
Content is automatically searched and collected through network algorithms . If there is a violation . Please contact us . We will adjust (correct author information ,or delete content ) as soon as possible .