57
Help us understand the problem. What are the problem?

More than 3 years have passed since last update.

posted at

updated at

Organization

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

使い方

% 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

使い方

% 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

使い方

% yarn add bootprint
% yarn add bootprint-openapi
% yarn bootprint openapi swagger.yml apidocs/bootprint-openapi
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away
Sign upLogin
57
Help us understand the problem. What are the problem?