[Swagger] OpenAPI3.0で記述したAPI仕様書をHTMLとして出力する

# Intro
[SwaggerUI](https://github.com/swagger-api/swagger-ui) を利用すると、OpenAPIで記述したAPI仕様書をHTTPサーバーとしてインターネットに公開したり、または ローカルにHTTPサーバーとして起動して確認できます。

チームで開発する場合、同じドキュメントを不特定多数のメンバーと共有して開発したくなるユースケースが発生することがあると思います。

`SwaggerUI` の [Docker Image](https://hub.docker.com/r/swaggerapi/swagger-ui/) をサーバーとして起動させ配信したりする方法もありますが、何らかの社内の事情で使えない場合や、もう少し簡単に始めたい場合に、HTMLファイルとして出力し、ブラウザで確認するというアプローチもあります。

# HTMLに変換してブラウザで確認する
OpenAPIで記述したファイルから、洗練されたスタイルが適用されたHTMLファイルにしてブラウザに確認するアプローチとしていくつかあります。

+ [swagger-codegen](https://github.com/swagger-api/swagger-codegen)
+ [swagger-ui](https://github.com/swagger-api/swagger-ui)
+ [redoc](https://github.com/Redocly/redoc)

以下のファイルを参考にそれぞれドキュメントを生成してみます。

```openapi.yaml
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger sample
paths:
  /users:
    get:
      summary: Usersを取得するAPIです。
      responses:
        '200':
          description: HTTPステータスコード200と以下の情報を含むJSONオブジェクトを返します。
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: string
                    example: 1234567
```

## swagger-codegen

swagger-codegen をインストールし実行するとHTMLが生成されます。

```
$ brew install swagger-codegen
```

```
$ swagger-codegen generate -i openapi.yaml -l html -o /tmp/swagger-sample
```
<img width="1114" alt="swagger-codegen.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/38342/166cf281-d3b0-2bef-c1e7-9b112f129dbd.png">



## swagger-ui

swagger-ui プロジェクト配下にある [dist](https://github.com/swagger-api/swagger-ui/tree/master/dist) ディレクトリに必要なファイルが一式あります。

自身が作成した仕様書を表示したい場合は `index.html` に記述されているリンクを変更すればOKです。ディレクトリ一式をWebサーバーへアップロードすれば `swagger-ui` のスタイルのままドキュメントを閲覧することができます。  


```
$ git clone git@github.com:swagger-api/swagger-ui.git
$ cd swagger-ui/dist
$ vi index.html
```

```index.html
     window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "https://petstore.swagger.io/v2/swagger.json",
+        url: "https://petstore.swagger.io/v2/swagger.yaml", ← ★ここを変更する★
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [
```

<img width="1414" alt="swagger-ui.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/38342/c4a4d410-8691-a67c-42f9-abe1c144964f.png">


## ReDoc
Redocを使うとデフォルトでかっこいいドキュメントが出来上がります。
個人的には3カラムのRedocのドキュメントが好みです。**[redoc demo](http://redocly.github.io/redoc/)**

[README](https://github.com/Redocly/redoc) に書かれているように基本的にはリンクを書き換えるだけで動作します。また [CLI](https://github.com/Redocly/redoc/tree/master/cli)も提供されているようです。今回はCliを使ってみます。

```
$ npm install -g redoc-cli
$ redoc-cli bundle openapi.yaml
```

<img width="1404" alt="redoc.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/38342/2eb4f240-98a3-2d32-5a29-4418a7c29889.png">

# まとめ
API仕様書を OpenAPI で記述していたら Swagger をはじめとした各種周辺ツールと簡単に連携できて良さそうです。

また、今回作成したHTMLを [AmazonS3](https://aws.amazon.com/jp/s3/)や [GithubPages](https://pages.github.com/) といったサービスにホスティングさせることでAPI仕様書をインターネットに公開も簡単に出来そうですね。

## 関連
+ [multi-file-swaggerでSwaggerファイルを分割してAPIドキュメントを管理する
](https://qiita.com/godgarden/items/963f0e28acaff8968f54)