Swagger UIをURLで共有できるようにしました

成果物はこちらです。
https://swagger-url.now.sh/

https://github.com/yousan/swagger-url

# Swagger
REST APIを使うプロジェクトでサーバサイドとフロントエンドで合意を取る際、APIの設計書があると便利です。
そのAPIの設計書としてはSwaggerがとても便利です。

[OpenAPI (Swagger) 超入門 - Qiita](https://qiita.com/teinen_qiita/items/e440ca7b1b52ec918f1b "OpenAPI (Swagger) 超入門 - Qiita")

SwaggerはSwaggerHubというサービスの上で編集、確認、共有することができますが、設計書となる構成ファイルの Swagger YAMLがプロジェクトのリポジトリから外れてしまいます。
そこでSwagger YAMLをプロジェクトのリポジトリに含めつつ、API設計の確認画面を共有できるようにしました。

# Swagger?
名前 | 役割
---|---
Swagger | REST APIを設計するための仕組み。
Open API | Swaggerを元に標準化された仕組み。Open API3.0として策定。
Swagger Hub | Swaggerを便利にチームで使うためのサービス。SwaggerとはGitとGitHubのような関係。
Swagger Editor | Swaggerを編集するために便利なエディタ（ブラウザで動作）
Swagger UI | Swaggerファイル（YAML、JSON）を読み込んで表示させるもの [今回のはこれ](https://swagger-url.now.sh/)

# Swagger UI
Swaggeｒで共有するために[Swagger UI](https://github.com/swagger-api/swagger-ui)があります。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/47327/f04c7fb3-c244-e88e-1d79-d307b9fcff33.png)

最終的にはこのSwagger UIの出力を確認していきます。

# 手を加えたこと
Swaggere UIではURLを入力することでYamlやJSONファイルをロードして出力してくれます。
Swagger UI公式にあるURLをロードする部分は下記です。

```javascript:index.html
   window.onload = function() {
      // Begin Swagger UI call region
      const ui = SwaggerUIBundle({
        url: "https://petstore.swagger.io/v2/swagger.json",
        dom_id: '#swagger-ui',
        deepLinking: true,
        presets: [
          SwaggerUIBundle.presets.apis,
          SwaggerUIStandalonePreset
        ],
        plugins: [
          SwaggerUIBundle.plugins.DownloadUrl
        ],
        layout: "StandaloneLayout"
      })
```

[Original](https://github.com/swagger-api/swagger-ui/blob/master/dist/index.html)

ここの`SwaggerUIBundle()`に渡している`url`をURLのクエリパラメータ（GETで取れる引数）として受け取れるようにします。


```javascript
     function get_url() {
        // @see https://stackoverflow.com/questions/35914069/how-can-i-get-query-parameters-from-a-url-in-vue-js
        let uri = window.location.href.split('?');
        if (uri.length === 2) {
          let vars = uri[1].split('&');
          let getVars = {};
          let tmp = '';
          vars.forEach(function (v) {
            tmp = v.split('=');
            if (tmp.length === 2)
              getVars[tmp[0]] = tmp[1];
          });
          return getVars.url;
        }
      }
```

またSwagger UIの上部にはURLを入力できるURL入力フォームがあります。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/47327/8f919291-f60c-a4cd-7b27-5c0e787ec404.png)


ここをクエリパラメータで受け取った`url`をその内容で埋めるようにします。

```javascript
      function set_url() {
        const button = document.getElementsByClassName("download-url-button")[0];
        const input = document.getElementsByClassName("download-url-input")[0];
        button.addEventListener("click", function() {
          window.location.search = 'url=' + encodeURIComponent(input.value);
        } , false);
      }
```

# デプロイ
デプロイはNow.shを利用しました。めっちゃ便利ですね！

[Now でクラウドの複雑さから解放されよう、今すぐに - Qiita](https://qiita.com/aggre/items/f0cb9f8b8e8c54768e50 "Now でクラウドの複雑さから解放されよう、今すぐに - Qiita")

# 使い方
GitHubでYamlファイルを管理し、ファイルへの直接リンクを"Raw"として取得します。

<img width="899" alt="Screen Shot 2019-11-24 at 14.03.27.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/47327/4f3c3622-7145-da18-baae-eb077700d8f9.png">

例えば次のようなURLになります。

```
https://raw.githubusercontent.com/swagger-api/swagger-samples/master/java/inflector-dropwizard/src/main/swagger/swagger.yaml
```

これを Swagger URLのURLに入力するとURLが引数として渡されます。

```
https://swagger-url.now.sh/?url=https%3A%2F%2Fraw.githubusercontent.com%2Fswagger-api%2Fswagger-samples%2Fmaster%2Fjava%2Finflector-dropwizard%2Fsrc%2Fmain%2Fswagger%2Fswagger.yaml
```

あとはこのURLをチームのSlackなどで共有することができます。便利！

# 参考情報
[Swaggerの概要をまとめてみた。 - Qiita](https://qiita.com/gcyata/items/342073fa7607fd4082bd "Swaggerの概要をまとめてみた。 - Qiita")


[Swaggerの記法まとめ - Qiita](https://qiita.com/rllllho/items/53a0023b32f4c0f8eabb "Swaggerの記法まとめ - Qiita")