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つだけなのでシンプル。

複数のサブディレクトリに分散されたjsonファイルに対して連続実行

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

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

その他の類似ツール

  • bootprint-openapi
  • swagger-codegen

参考

https://stackoverflow.com/questions/25800493/converting-swagger-specification-json-to-html-documentation

コメントを残す

メールアドレスが公開されることはありません。