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

ただの感想です。

[Community-Driven Tools](https://swagger.io/tools/open-source/open-source-integrations/#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
- 見た目: そこそこ
- レスポンスの定義: モデルへのリンク
- 感想:
  - まぁまぁ。

### 使い方

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
- 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 で書いたドキュメントに組み込むならありかも。
    - 多分 ライブラリとして使えばいろいろやれる。

### 使い方

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

- 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
```