Swagger-Spec ファイルから APIドキュメントを生成するツールをいくつか試してみた

yml 形式の Swagger-Spec ファイルを指定して、コマンド１発で静的ページの APIドキュメントを作ってくれるツールってないかな、と思ったら結構色々見つかったので試してみた。

静的ページを作ってくれるわけではなく、Webサーバで動かす事を前提としたツールもいくつかあったので、それらについてはデモ画面にて。

静的ページを作成できた

• bootprint-openapi
• redoc-cli

公式デモ

• redoc
• Swagger UI
• spectacle
• Swagger2Markup

「bootprint-openapi」がお手軽で使いやすいのではないでしょうか。
生成されるドキュメントも、よく見る形ですし。

リポジトリのみで管理するなら、公開範囲をどうするかがネックか。
bitbucket の場合、融通がきかないうえ、チームのみの公開という設定ができないみたいだし。

ただ、コマンド１発で生成できたりするので、
リポジトリで管理して push -> CI/CDツールでAPIドキュメントを自動生成
という動きもできるんじゃないかと思います。

とは言いつつも、PostmanにSwagger specファイルを食わせた方がよくね？
と思ってきたわけですが、それはまた次回に。

以下、使ってみたツールの詳細。

bootprint-openapi

https://github.com/bootprint/bootprint-openapi

使い方

（インストール）
npm install -g bootprint
npm install -g bootprint-openapi

（使い方）
bootprint openapi <出力したYAMLかJSONファイル> <出力先ディレクトリ>

（使用例）
bootprint openapi swagger_sample01.yml bootprint_sample

redoc

https://github.com/Redocly/redoc

公式デモ

http://redocly.github.io/redoc/

備考

静的ページをジェネレートするわけではなく、Webサーバで動かす事を前提としているみたい

redoc-cli

https://github.com/Redocly/redoc

使い方

（インストール）
npm install -g redoc-cli

（使い方）
redoc-cli bundle <Swaggerファイル>
redoc-cli bundle <Swaggerファイル> -o <出力ファイル名>

（使用例）
redoc-cli bundle swagger_sample01.yml
redoc-cli bundle swagger_sample01.yml -o swagger_sample01_redoc-cli/index.html

備考

マニュアルの説明が簡略化され過ぎて、何書いてるのかよくわかんない

Swagger UI

公式デモ

https://petstore.swagger.io/

備考

静的ページをジェネレートするわけではなく、Webサーバで動かす事を前提としているみたい

spectacle

公式デモ

http://cheesestore.github.io/

使い方

npm install -g spectacle-docs
spectacle -d <your_swagger_api.json>

使えるのは json のみ？
yml にしたいんだけど・・・

Swagger2Markup

公式デモ

http://swagger2markup.github.io/spring-swagger2markup-demo/1.1.0/

備考

お手軽さを全く感じない。
yml ファイルからちゃちゃっとページを作る、というレベル感で使う物ではなさそうな気がしてきた。