Swagger - ファイル分割とリアルタイムプレビューで快適にAPIドキュメントを作成したかった。
# docker # swagger
どうも皆さんSwagger（OpenAPI）書いてますかーー！！ 僕は書くのが辛いですが、書かないと後の自分がもっとつらいことが目に見えている（そりゃそうです）ので書いています。 そんなSwaggerファイルですが、少しでも楽に書けるように工夫をしてみました。
複数ファイルでSwaggerを管理したかった
Swaggerファイルが巨大になる匂いを感じたので、分割して管理をしたかったのです。 記述がyaml or json なので数1,000行とかになったり使い回し利かなかったり、色々と融通が利きません。
一応分割は出来るらしいですが、バグがあったりSwaggerHubが1ファイル前提だったりと使いにくい部分が多いのです…。
既に同様の課題を抱えている人は多く、実例もありました。
Swaggerをファイル分割しながら、編集できるものを作成しました。
自分がやりたいようにするため、上記の記事の内容とも被りが多くありますが、
- 環境構築とか面倒なので、Docker-composeで何も考えずに環境作れる
- Swaggerファイルを分割して管理 + 変更時は自動で1ファイルに結合する
- 深い階層の変更も監視を行う**（New）**
- Swagger定義ファイルが更新された際にホットリロード**（New）**
- 自分の好きなようにディレクトリ名・構造を変更
というようなものとなりました。
これで多少はSwaggerの構築・運用が楽になるはず。 普段webpackとか自分で書くことが無いので詰まりながらですが、恩恵は十分にあるはずなのです。
全ソースはGitHub（こちら）においてあるので、良かったら使って見て下さい。
変更した点
Nginxではなくwebpack-dev-serverを使用するように変更
Nginxはホットリロード機能がついていない（多分）なことと、webpack-dev-serverを使用するための設定が元々swagger-uiのgitリポジトリにあるので、そちらを使う形としました。
ただ、設定ファイルに多少変更を加えたりした（下記参照）関係で、npxコマンドを自由にコマンドを実行したかったのですが、 DockerHubに上がっているswagger-uiのDockerImageでは、npxコマンドが使えなかったため、git hub から直接ソースをダウンロードするようにしています…。
webpack-dev-serverの設定変更
swagger-uiのDockerコンテナの中に、「swagger-ui/webpack/dev.babel.js」というフォルダがありますが、このままだと
- swagger.yamlが変更監視対象に入らない
- ファイルシステムの環境からDocker環境でのホットリロードが成り立たない（らしい）
のでconfigに以下の内容を追記します。
# webpack-dev-serverでの変更監視の対象とするために追加
Object.assign(devConfig.entry, {
"swagger-yml": "./dev-helpers/swagger.yaml"
})
# Docker環境での変更監視のために追加
devConfig.watchOptions = {
aggregateTimeout: 300,
poll: true,
ignored: [ 'node_modules' ]
}
なお、色々設定がされていて、それらをコピペするのも冗長なので、直接ファイルを編集する形ではなく既存設定に追加をする形としました。
課題
本当はHot Module Replacementをしたかったのですが、力不足で上手くいきませんでした…。
とはいえ、一旦やりたいことに対しては十分なので良いSwaggerライフを送れると信じます！