TL;DR
Swagger Editorで作成したyamlファイルとSwagger UIを利用してPHP、python、rubyのビルトインサーバで動作させます。
VS Code の拡張機能「Swagger Viewer」を使う手もあります。
code --install-extension Arjun.swagger-viewer
本記事ではnode.jsを利用した Web サーバは使用しません。
手順
1. Swagger Editor で yaml を作成する
Swagger Editotでyamlファイルを作成します。
作成したyamlファイルはメニューの「File」→「Save as YAML」からswagger.yamlというファイル名でダウンロードできます。
2. Swagger UI をダウンロードする
GitHub の Swagger UI から zip でダウンロードして、distフォルダ以下を取り出します。
3. Swagger UI を改造する
dist/swagger-initalizer.jsを以下のように変更し、任意の URL のyamlファイルを URL パラメータで指定できるようにします。
@yousan さまの記事「Swagger UIをURLで共有できるようにしました」をほぼそのまま利用しています。ありがとうございます！
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サーバを集めてみた」を参考にしています。ありがとうございます！
まずはターミナルを起動して、ダウンロードした Swagger UI のdistフォルダへ移動します。
# パスはご自分の環境に合わせて読み替えてください
cd /path/to/swagger-ui/dist/
distフォルダ内で下記コマンドを実行します。
php -S 0.0.0.0:8000
python3 -m http.server 8000
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 の画面が表示されれば成功です！
おまけ
実は VS Code の拡張機能「Swagger Viewer」を使えばビルトインサーバを建てる必要すらありません。
VS Code がインストールされていれば以下のコマンドでインストールできます。
code --install-extension Arjun.swagger-viewer
おまけ2
distディレクトリ以下を開発用の Web サーバにアップロードすることでリポジトリの外に Swagger UI だけを公開することもできますね。