redoc-cliを使ってOpen API jsonファイルから整形されたhtmlを生成

頻繁に利用しているRESTful APIはswagger-uiを使ってAPI参照している。ただそのAPIに直接アクセスできない人に、これを単純なファイルとして渡すには難儀。

ということで調べてみたらredoc-cliってのが出てきた。こいつが便利だったのでちょっと整理。

簡単にいうとjson specificationを整形された読みやすいhtmlに変換してくれる。そして使い方があまりにも簡単。

インストール

npmでインストールするのでnode.jsとnpmがインストールされていることが前提

npm install -g redoc-cli

npmでrecoc-cliをインストールしたら以下のコマンドを実行するだけ

redoc-cli bundle [jsonファイル] -o [出力ファイル名]

jsonファイルがswagger.json、出力ファイルをindex.htmlとする場合の実行コマンドは以下の通り

redoc-cli bundle swagger.json -o index.html

出力されたindex.htmlをブラウザで開くと以下のようなフォーマットで中身を参照することが可能。ファイルは1つだけなのでシンプル。

参考まで、サブディレクトリに保存された複数の swagger.json ファイルに対してコマンド実行するサンプル

for file in */swagger.json;do redoc-cli bundle -o ${file%swagger.json}index.html $file;done