SwaggerUIを簡単にGithub Pagesで公開する方法

# 背景
Swagger超初心者かつQiita初投稿です。

SwaggerでAPIドキュメントを書いてGithub Pagesで簡単に講師する方法をまとめます。
サーバーをもたないでとりあえず仕様書を見せれるようにしたいときにどうぞ。
（Swagger初心者で同じように困っている人に役立てれば…!）

下記のgithubに書かれていた内容を少し変更してやってみた感じです
https://github.com/peter-evans/swagger-github-pages

# 操作
## 0.準備
Github Pagesで最終的に公開するための`docs`ディレクトリと、とりあえずサンプルで公開したい`swagger.yaml`を用意します。

```:ディレクトリ構成
.
└── docs
    └── swagger.yaml
```
```yaml:docs/swagger.yaml
swagger: '2.0'
info:
  version: 1.0.0
  title: タイトル
paths:
  '/user/{id}':
    get:
      description: ユーザー情報取得
      parameters:
      - name: id
        in: path
        description: user id
        required: true
        type: number
      responses:
        '200':
          description: 成功
          schema:
            type: object
            properties:
              id:
                type: integer
              username:
                type: string
```

## 1. Swagger UIのソースコードを取得
Swagger UIの[Github](https://github.com/swagger-api/swagger-ui)からソースコードを取得します。

今回は手っ取り早くZIPでダウンロードします。
https://github.com/swagger-api/swagger-ui/archive/master.zip

##2. `dist`ディレクトリを`docs`に追加
`dist`ディレクトリのみ使用するのでZIPファイルから解凍して、`docs`以下に配置します。


```bash:docs以下に展開
$ mkdir docs/dist
$ unzip -d docs/dist -j ~/Downloads/swagger-ui-master.zip */dist/*
```
* `~/Downloads/swagger-ui-master.zip`は1で取得したZIPファイル

##3. `index.html`の修正
`docs/dist/index.html`のSwaggerファイルのパスを修正して、用意したSwaggerファイルへ変更します。

```diff:docs/dist/index.htmlのdiff
     window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "https://petstore.swagger.io/v2/swagger.json",
+        url: "../swagger.yaml", // my swagger file
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [
```

##4. githubへpush
これでファイルの準備は完了したので、ファイルをすべてコミットしてgithubへpushします。

```:最終的なファイル構成
.
└── docs
    ├── dist
    │   ├── favicon-16x16.png
    │   ├── favicon-32x32.png
    │   ├── index.html
    │   ├── oauth2-redirect.html
    │   ├── swagger-ui-bundle.js
    │   ├── swagger-ui-bundle.js.map
    │   ├── swagger-ui-standalone-preset.js
    │   ├── swagger-ui-standalone-preset.js.map
    │   ├── swagger-ui.css
    │   ├── swagger-ui.css.map
    │   ├── swagger-ui.js
    │   └── swagger-ui.js.map
    └── swagger.yaml
```

##5. Github Pagesの設定
Githubへのpushが完了したら設定をしてGithub Pagesで公開します。

1. GithubのSettingsを開く
2. 「GitHub Pages」の「Source」を「**master branch /docs folder**」へ変更(初期値は「None」)
3. すぐ横の「**Save**」で保存

これでGithub Pagesでの公開が完了です。

##6. ブラウザでアクセス
これで設定がすべて完了したのでブラウザでアクセスできるようになっています。
ブラウザで下記のURLにアクセスして表示できたら完了です。
`https://<username>.github.io/<repository>/dist/index.html`
![image.png](https://qiita-image-store.s3.amazonaws.com/0/364735/94d405ba-477b-5f8d-53e4-d0fa5411677f.png)

# まとめ
これでサーバーとかをもたずに、Swaggerファイルを変更するだけで最新のAPI仕様書が公開できるようになります。

上記の操作したGithubはこちらになります。

* Github
    * https://github.com/youdays/swagger-hosting-sample
* Github Pages
    * https://youdays.github.io/swagger-hosting-sample/dist/index.html

# 余談
今の`index.html`は`dist`ディレクトリの下にあるため、URLにもdistが含まれてしまってます。
省略させたい場合は、`index.html`を修正するとできます。

* `index.html`を上の階層へ移動する
    * `docs/dist/index.html` => `docs/index.html`
* Swaggerファイルなどのパスを変更する

```diff
@@ -4,9 +4,9 @@
   <head>
     <meta charset="UTF-8">
     <title>Swagger UI</title>
-    <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
-    <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
-    <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
+    <link rel="stylesheet" type="text/css" href="dist/swagger-ui.css" >
+    <link rel="icon" type="image/png" href="dist/favicon-32x32.png" sizes="32x32" />
+    <link rel="icon" type="image/png" href="dist/favicon-16x16.png" sizes="16x16" />
     <style>
       html
       {
@@ -33,13 +33,13 @@
   <body>
     <div id="swagger-ui"></div>

-    <script src="./swagger-ui-bundle.js"> </script>
-    <script src="./swagger-ui-standalone-preset.js"> </script>
+    <script src="dist/swagger-ui-bundle.js"> </script>
+    <script src="dist/swagger-ui-standalone-preset.js"> </script>
     <script>
     window.onload = function() {
       // Begin Swagger UI call region
       const ui = SwaggerUIBundle({
-        url: "../swagger.yaml", // my swagger file
+        url: "./swagger.yaml", // my swagger file
         dom_id: '#swagger-ui',
         deepLinking: true,
         presets: [
```