swagger
OpenAPI

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


使い方

https://github.com/sourcey/spectacle#usage

% 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


使い方

http://swagger2markup.github.io/swagger2markup/1.3.3/#_docker_image

% 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生成

  • 見た目: なかなか

  • レスポンスの定義: 埋め込み

  • 感想


    • よさげ。

    • 動的にページ作るところがちょっと遅い。

    • 色味程度ならカスタマイズできる。

    • ベンダープレフィクス付きの属性で付加情報を付けられる。




使い方

https://github.com/Rebilly/ReDoc#tldr

% 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 になる。




使い方

https://github.com/Rebilly/ReDoc/blob/master/cli/README.md#usage

% 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


使い方

% yarn add bootprint

% yarn add bootprint-openapi
% yarn bootprint openapi swagger.yml apidocs/bootprint-openapi