Swaggerを使ってAPIのドキュメントを作る話。

公式

Swagger-EditorとかUIとか使えばとりあえずすぐ使える。

公式のツール群は素晴らしいと思うのですが、

ある程度規模が大きくなると、ちょっと無理。

何でかって言うと、ソースが1ファイルだから。

大きくなると行数とか普通に万超えるので。

メンテが無理。

あと、Swagger-UIって1ページに全部ずらっと並べるので

数が多くなってくるとますます無理。

なので、ソースのyamlファイルを分割するのと、

静的なHTMLファイルを作るコンバータみたいなのが欲しい。

と思ってたらやっぱりありますね。

色々あるのですが、公式がまとめてる一覧はこちら

で、最終的に下記の構成にした

Yaml⇒HTMLのコンバータはどれもYamlファイル自体は1ファイルにまとまってないとダメなので、

分割したYamlを一つのファイルにまとめるツールが必要。

で、それをやるのに「multi-file-swagger」と「swagger-merger」があるのですが(他にもあると思うけど)、今回は「swagger-merger」を利用。npmのサイト的にこっちの方がちゃんとドキュメント書いてそうだったので。そういうの大事。

npm install --save-dev swagger-merger

# 実行はこんな感じ
swagger-merger -i ./src/index.yaml -o swagger-tmp.yaml

YAMLが出来たらRedocでHTMLにする。

npm install --save-dev redoc-cli

# 実行はこんな感じ
redoc-cli bundle swagger-tmp.yaml

で、これだと修正しながらブラウザで確認できないので、

なんちゃってホットリロードが出来るようにする。

# 必要なモジュール
npm install --save-dev npm-run-all
npm install --save-dev watch
npm install --save-dev light-server

# ソースディレクトリの更新を監視して、更新されたらmakeを流す
watch \"npm run make\" ./src

# HTMLを監視して更新されたらホットリロードする
light-server -s ./dist -p 4000 -w \"./dist/*.html # # reload\"

もろもろやったサンプルはここにあげた。

ファイルの分割の書き方なんかも↑のリポジトリのsrc内参照。

あと、Redocも素晴らしいのですが、若干ん?って思うところもある。

左メニューの各APIへのリンクがsummryになってるのですが、

ここってURLというかYAMLのタグにならないもんだろうか。。。

他のHTML作るツールも軒並みsummary使ってるので、こっちが主流なのかしら?