かきノート

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

April 20, 2021 • ☕️ 4 min read

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

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

静的ページを作成できた

公式デモ

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

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

ただ、コマンド1発で生成できたりするので、
リポジトリで管理して 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 ファイルからちゃちゃっとページを作る、というレベル感で使う物ではなさそうな気がしてきた。


Relative Posts:

bitbucket で、github pages のように静的ページを公開してみる

April 19, 2021

福岡の物流エンジニアが、七転び八起きしたあと九回転び、寝っ転がったまま何かやってる事を垂れ流しているブログ

RotateLinkImg-iconRotateLinkImg-iconRotateLinkImg-iconRotateLinkImg-icon