Help us understand the problem. What is going on with this article?

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

More than 1 year has passed since last update.

ただの感想です。

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
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
Comments
No comments
Sign up for free and join this conversation.
If you already have a Qiita account
Why do not you register as a user and use Qiita more conveniently?
You need to log in to use this function. Qiita can be used more conveniently after logging in.
You seem to be reading articles frequently this month. Qiita can be used more conveniently after logging in.
  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
ユーザーは見つかりませんでした