Swagger UI をローカルで動かす

## TL;DR

[Swagger Editor](https://editor.swagger.io/)で作成した`yaml`ファイルと[Swagger UI](https://github.com/swagger-api/swagger-ui)を利用して`PHP`、`python`、`ruby`のビルトインサーバで動作させます。

VS Code の拡張機能「Swagger Viewer」を使う手もあります。
```sh:Swagger&nbsp;Viewerのインストールコマンド
code --install-extension Arjun.swagger-viewer
```

本記事では`node.js`を利用した Web サーバは使用しません。

## 手順

### 1. Swagger Editor で yaml を作成する 

[Swagger Editot](https://editor.swagger.io/)で`yaml`ファイルを作成します。
作成した`yaml`ファイルはメニューの「File」→「Save as YAML」から`swagger.yaml`というファイル名でダウンロードできます。

### 2. Swagger UI をダウンロードする

GitHub の [Swagger UI](https://github.com/swagger-api/swagger-ui) から zip でダウンロードして、`dist`フォルダ以下を取り出します。

### 3. Swagger UI を改造する

`dist/swagger-initalizer.js`を以下のように変更し、任意の URL の`yaml`ファイルを URL パラメータで指定できるようにします。
@yousan さまの記事「[Swagger UIをURLで共有できるようにしました](https://qiita.com/yousan/items/add59d15eae221d5e1b5)」をほぼそのまま利用しています。ありがとうございます！

```js:dist/swagger-initalizer.js
window.onload = function () {
  // ここにコピペ
  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;
    }
  }
  // ここまでコピペ
  //<editor-fold desc="Changeable Configuration Block">

  // the following lines will be replaced by docker/configurator, when it runs in a docker-container
  window.ui = SwaggerUIBundle({
    // url: "https://petstore.swagger.io/v2/swagger.json", // ←ここを書き換え
    url: get_url(), // ←ここを書き換え
    dom_id: '#swagger-ui',
    deepLinking: true,
    presets: [
      SwaggerUIBundle.presets.apis,
      SwaggerUIStandalonePreset
    ],
    plugins: [
      SwaggerUIBundle.plugins.DownloadUrl
    ],
    layout: "StandaloneLayout"
  });

  //</editor-fold>
};
```

これで`http://サーバ名/?url=http://サーバ名/swagger.yaml`という URL で公開されている任意の`yaml`ファイルを読み込むことができるようになりました。

### 4. ビルトインサーバを実行する

ビルトインサーバ（言語処理系が持っている Web サーバ）を使って Swagger UI を表示できるようにします。
サーバを使わず`dist/index.html`を開いても`yaml`ファイルを読み込むところでうまく動きません。

ここでは @sudahiroshi さまの記事「[ワンライナーWebサーバを集めてみた](https://qiita.com/sudahiroshi/items/e74d61d939f18779970d)」を参考にしています。ありがとうございます！

まずはターミナルを起動して、ダウンロードした Swagger UI の`dist`フォルダへ移動します。

```sh
# パスはご自分の環境に合わせて読み替えてください
cd /path/to/swagger-ui/dist/
```

`dist`フォルダ内で下記コマンドを実行します。

```sh:phpの場合
php -S 0.0.0.0:8000
```

```sh:python3の場合
python3 -m http.server 8000
```

```sh:rubyの場合
ruby -rwebrick -e 'WEBrick::HTTPServer.new(:DocumentRoot => "./", :Port => 8000).start'
```

### 5. ビルトインサーバからアクセスできる範囲に yaml ファイルを設置する

`dist`フォルダ内においておけば問題ありません。
必要に応じて`docs`フォルダなどを作成してその中に`yaml`ファイルを設置しても良いでしょう。

### 6. ビルトインサーバにアクセスする

上記手順のとおりにしていれば、下記リンクにアクセスすることでローカルにあるビルトインサーバの Swagger UI にアクセスできます。

<http://localhost:8000/?url=http://localhost:8000/swagger.yaml>

Swagger UI の画面が表示されれば成功です！

<img src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/76242/83a77d42-cecf-3c30-1bfc-438a4ebaa9fd.png" width=800>

## おまけ

実は VS Code の拡張機能「Swagger Viewer」を使えばビルトインサーバを建てる必要すらありません。
VS Code がインストールされていれば以下のコマンドでインストールできます。

```sh
code --install-extension Arjun.swagger-viewer
```

## おまけ2

`dist`ディレクトリ以下を開発用の Web サーバにアップロードすることでリポジトリの外に Swagger UI だけを公開することもできますね。