swaggerをjsonで書いて、ついでに分割して管理する

概要

タイトルの通り。
コードが肥大するので分割して管理する。
jsonでやってますが、スクリプトの拡張子変更すればyamlでもいけるはず。

完成物

アーキテクチャ

• swagger
  • v3.0.0
• swagger-cli
  • bundle担当
• chokidar
  • ファイル監視
• Swagger Viewer
  • VSCの拡張機能

ディレクトリ構造

root
├── docs
│   ├── paths 　　　　 // 監視対象ディレクトリ
│   ├── info
│   ├── _index.json  // rootファイル
│   └── swagger.json // bundleされたファイル
└── package.json

手順

1. packageなどをインストール

$ npm i -D swagger swagger-cli chokidar chokidar-cli

2. npmスクリプト編集

"scripts": {
  "build:swagger": "swagger-cli bundle ./docs/_index.json > ./docs/swagger.json",
  "watch:swagger": "chokidar './docs/paths' -c 'npm run build:swagger'"
}

3. スクリプトを実行してファイルを監視

$ npm run watch:swagger

4. VSCで swagger.json を Swagger Viewer で開く

swagger.json を開いて(activeにして)から、 Command + Shift + p を押下し、
OpenAPI: show preview using~ を選択する。
previewが展開されればOK。