ただの感想です。
Community-Driven Tools にあるものから以下を試してみました。
- spectacle
- swagger2markup
- swagger-codegen
- redoc
- redoc-cli
- swagger-ui
- bootprint-openapi
一通り試した結果 redoc-cli が速度と見た目を両立していて、個人的にはこれを使うのが一番良いのではと思います。動的に作られる swagger.yml, swagger.json を読みたいなら redoc ですかねぇ。
spectacle
- URL: https://github.com/sourcey/spectacle
- Star: 648
- Demo: http://cheesestore.github.io/
- 対応バージョン: OpenAPI 2.0
- 方式: 静的HTML
- 見た目: そこそこ
- レスポンスの定義: モデルへのリンク
- 感想:
- まぁまぁ。
使い方
% yarn add spectacle-docs
% spectacle -t apidocs/spectacle swagger.yml
または
% docker run --rm -v $(pwd):/pwd sourcey/spectacle spectacle -t /pwd/apidocs/spectacle /pwd/swagger.yml
swagger2markup
- URL: https://github.com/Swagger2Markup/swagger2markup
- Star: 1322
- Demo: http://swagger2markup.github.io/spring-swagger2markup-demo/1.1.0/
- 対応バージョン: OpenAPI 2.0
- 方式: Markdown or AsciiDoc を出力
- 見た目: Javaっぽい
- レスポンスの定義: モデルへのリンク
- 感想:
- markdown は asciidoc で書いたドキュメントに組み込むならありかも。
- 多分 ライブラリとして使えばいろいろやれる。
使い方
% docker run --rm -v $(pwd):/pwd swagger2markup/swagger2markup convert -i /pwd/swagger.yml -f /pwd/apidocs/swagger2markup/index
swagger-codegen + static html generator
- URL: https://github.com/swagger-api/swagger-codegen
- Star: 7500
- Demo: N/A
- 対応バージョン: OpenAPI 2.0, 3.0 (stable は 2.0 のみ)
- 方式: 静的HTML
- 見た目: ださい
- レスポンスの定義: モデルへのリンク
- 感想:
- ださい。
- swagger-codegen で static html output plugin を使ったもの。
- 自分で出力 plugin を書けばなんとでもなる話ではある。
使い方
https://github.com/swagger-api/swagger-codegen#swagger-codegen-cli-docker-image
https://github.com/swagger-api/swagger-codegen#generating-static-html-api-documentation
% docker run --rm -v $(pwd):/pwd swaggerapi/swagger-codegen-cli generate -l html -i /pwd/swagger.yml -o /pwd/apidocs/swagger-codegen
redoc
- URL: https://github.com/Rebilly/ReDoc
- Star: 3200
- Demo: http://rebilly.github.io/ReDoc/
- 対応バージョン: OpenAPI 2.0, 3.0
- 方式: 静的JS + swaggr.yml で動的HTML生成
- 見た目: なかなか
- レスポンスの定義: 埋め込み
- 感想
- よさげ。
- 動的にページ作るところがちょっと遅い。
- 色味程度ならカスタマイズできる。
- ベンダープレフィクス付きの属性で付加情報を付けられる。
使い方
% mkdir -p apidocs/redoc
% cp swagger.yml apidocs/redoc/
% curl https://gist.githubusercontent.com/buzztaiki/5604a36278bc2efc3056f343e0e1f8d5/raw/590e2a49148272a2b3e256a3ff7948f4f3576ec2/redoc.html > apidocs/redoc/index.html
ただのhtmlとしては見れないので適当に httpd を動かす。
% busybox httpd -p 4000 -f -h apidocs/redoc
redoc-cli
- URL: https://github.com/Rebilly/ReDoc
- Star: 3200
- Demo: N/A
- 対応バージョン: OpenAPI 2.0, 3.0
- 方式: 静的HTML
- 見た目: なかなか
- レスポンスの定義: 埋め込み
- 感想
- redoc の静的HTML版。
- 速い。
- 2.0 の yaml を食べさせてもダウンロードリンクが 3.0 の json になる。
使い方
% yarn add redoc-cli
% redoc-cli bundle swagger.yml -o apidocs/redoc-cli/index.html
swagger-ui
- URL: https://github.com/swagger-api/swagger-ui
- Star: 12000
- Demo: https://petstore.swagger.io/
- 対応バージョン: OpenAPI 2.0, 3.0
- 方式: 静的JS + swaggr.yml で動的HTML生成
- 見た目: そこそこ
- レスポンスの定義: 埋め込み
- 感想
- swagger 標準。
- try it out で確認ができる。
- plugin を使って拡張もできる。
- ちょっと見ずらいかなぁって感じはある。
使い方
% mkdir -p apidocs/swagger-ui
% cp swagger.yml apidocs/swagger-ui/
% curl https://gist.githubusercontent.com/buzztaiki/e243ccc3203f96777e2e8141d4993664/raw/0bcbbf52cf500221c0f26bbe81124be4f4c48249/swagger-ui.html > apidocs/swagger-ui/index.html
ただのhtmlとしては見れないので適当に httpd を動かす。
% busybox httpd -p 4000 -f -h apidocs/swagger-ui
bootprint-openapi
- URL: https://github.com/bootprint/bootprint-openapi
- Star: 250
- Demo: N/A
- 対応バージョン: OpenAPI 3.0
- 方式: 静的HTML
- 見た目: いまいち
- レスポンスの定義: モデルへのリンク
- 感想
- なんかあれ。
使い方
% yarn add bootprint
% yarn add bootprint-openapi
% yarn bootprint openapi swagger.yml apidocs/bootprint-openapi