OpenAPI (Swagger) API仕様を無料で手軽にWeb公開する

OpenAPI Specification (またはSwagger) を、
無料で手軽にWeb公開する方法をご紹介します。

この記事では、OpenAPIそのもの、OpenAPI Specificationについては言及しません。

## 🚨注意🚨
この記事で紹介する方法はパブリックな共有方法になります。
アクセス制限等が必要な場合は別途考慮する必要があります。


# 概要
- OpenAPI Specification (またはSwagger) のyamlファイル
- ReDocを採用したhtmlファイル

これらをgithubにpushし、GitHub Pagesでホスティングします。

# 手順
## yamlファイルを作成する
なにはともあれ、API仕様を定義したyamlファイルが必要です。

- Swagger Editor
手軽なものですと、Swaggerが公式で提供しているSwagger Editorがあります。
ブラウザでyamlファイルを編集することができます。
[editor.swagger.io](https://editor.swagger.io)

- Swagger Viewer
VSCodeのプラグインでyamlをプレビューできるものがあります。
[Swagger Viewer](https://marketplace.visualstudio.com/items?itemName=Arjun.swagger-viewer)

## Htmlファイルを作成する
yamlファイルを静的なhtmlに変換するツールはいくつかあります。
OpenAPI公式が公開している [openapi-generator](https://github.com/OpenAPITools/openapi-generator#overview) も機能を提供しています。

今回は手軽に利用できる [ReDoc](https://github.com/Redocly/redoc) を使います。

⭐️ReDocの特徴は **yamlからhtmlへの変換作業が不要** なことです

htmlファイルのテンプレートは[github](https://github.com/Redocly/redoc#tldr)に公開されています。
テンプレートの`<redoc>`タグはyamlファイルへのパスを指定します。

例として、以下のような構成のgitリポジトリを作成します。
(後ほどGitHub Pagesでホスティングするため、gitリポジトリをベースに考えます)

```
/{repo_root}
  ├─ index.html
  └─ wabapi.yml
```

この場合、htmlファイルは以下のようになります。

```html
<!DOCTYPE html>
<html>
  <head>
    <title>ReDoc</title>
    <!-- needed for adaptive design -->
    <meta charset="utf-8"/>
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">

    <!--
    ReDoc doesn't change outer page styles
    -->
    <style>
      body {
        margin: 0;
        padding: 0;
      }
    </style>
  </head>
  <body>
    <!-- 👇yamlファイルへのパス -->
    <redoc spec-url='./webapi.yaml'></redoc> 
    <script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"> </script>
  </body>
</html>
```

## GitHubにリポジトリを用意する
GitHub Pagesで公開するには、関連するリポジトリが必要です。

GitHub Pagesで公開できる単位は3つです。
1. プロジェクト
2. ユーザー
3. Organization

当然、ユーザー単位で公開できるGitHub Pagesは1ユーザーあたり1つまでとなります。

### ユーザーまたはOrganizationで公開
リポジトリ名を `<user>.github.io` または `<organization>.github.io`とした場合、
`master` ブランチの内容が、以下のURLで公開されます。
`http(s)://<user>.github.io/`
`http(s)://<organization>.github.io/`

これらは特に設定は不要です。自動的に公開されます。

### プロジェクトで公開
リポジトリ名は自由です。
ブランチは`master`または`gh-pages`のいずれかを選択できます。
デフォルトで以下のようなドメインで公開されます。
`http(s)://<user>.github.io/<repository>`
`http(s)://<organization>.github.io/<repository>`

これらは公開ソースのブランチの設定が必要です。
<img width="914" alt="スクリーンショット 2020-04-12 15.46.12.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/14646/8979a1a6-7c5f-5adf-d08d-08df189127ba.png">
<img width="655" alt="スクリーンショット 2020-04-12 15.46.21.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/14646/4f48b31b-7c9c-4cba-9d29-956b02e84ec7.png">


### GitHub Pages 早見表
||ユーザーまたはOrganizationで公開|プロジェクトで公開|
|:--|:--|:--|
|GitHubのリポジトリ名|`<user>.github.io` <br>または<br> `<organization>.github.io`|自由|
|公開ソースのブランチ| `master` | `master` <br>または<br> `master`の/docs配下 <br>または<br> `gh-pages` |
|公開URL|`http(s)://<user>.github.io/` <br>または<br> `http(s)://<organization>.github.io/` | `http(s)://< user >.github.io/<repository>` |

## GitHubにPushする
- 作成したyamlファイル
- 前項で示したhtmlファイル

この2点を以下のような構成でGitHubにPushします。

```
/{repo_root}
  ├─ index.html
  └─ wabapi.yml
```

公開ソースのブランチにPushまたはMergeしましょう。

### ブラウザで確認する
この[早見表](https://qiita.com/watanave/items/1a43ec998121d0f06832#github-pages-早見表)を参考にブラウザで公開されているかどうか確認します。
GitHubにPushしてから **最大で20分ほど** かかることがあるようです。

# まとめ
- ReDocは yamlからhtmlへの変換が不要で手軽です
- github pagesは静的ページをホスティングできます
- github pagesのリポジトリ名、公開ソースブランチ制約は[早見表](https://qiita.com/watanave/items/1a43ec998121d0f06832#github-pages-早見表)を参考に

# (採用例) 北海道コロナ情報まとめサイト
https://stopcovid19.hokkaido.dev

OSSで開発されている北海道のコロナ情報まとめサイトは、
**北海道のコロナ感染情報をWebAPIで公開しています。**

このAPI仕様はこの記事の技術で公開されています。
https://codeforsapporo.github.io/covid19hokkaido_webapi/