ReDocを用いたAPI仕様書の作成手順

ReDocとは

ReDocとは、OpenAPI/Swagger仕様で記述されたyamlファイルからhtmlファイルを生成し、静的なドキュメント作成をするツール。

API仕様書の作成手順

動作環境

MacOS Catalina

Step1: nodebrewのインストール

brew install nodebrew
nodebrew -v
nodebrew ls-remote
nodebrew setup
echo 'export PATH="$HOME/.nodebrew/current/bin:$PATH"' >> ~/.bash_profile

Step2: nodeのインストール

nodebrew install-binary stable
nodebrew ls
nodebrew use stable
nodebrew ls
node -v

Step3: yarnのインストール

brew install yarn
yarn -v

Step4: yarnを用いたReDocのインストール

mkdir redoc_sample
cd redoc_sample
yarn add redoc
yarn add redoc-cli
yarn list redoc

Step5: swagger.ymlの作成

vim swagger.yml

swagger.ymlの作成例等を参考にOpenAPI/Swaggerフォーマットに則りyamlファイルを作成

Step6: ymlからhtmlへの変換(API仕様書ページの作成)

npx redoc-cli bundle swagger.yml -o index.html
open index.html