Swagger Specから静的なHTMLを作るHTMLジェネレータを色々ためしてみた

ただの感想です。

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