swagger-mergerを使ってswaggerファイルを分割管理しよう

Programming

APIの管理にswagger(現openapi3.0)を使用している組織は多いかと思います。

そこでよく出てくる問題として、swagger(openapi)ファイルを長い間運用し続けていると、pathsやcomponentsが無制限に増えて長大になりやすくなります。

これは可読性や保守性(特に多人数でのgit管理におけるconflict)を著しく損なうため、swagger-mergerを用いたファイル分割管理をお勧めします。

運用手順の概要としては、①ファイルを分割して作成し、②manifestファイルに参照先をまとめ、③swagger-mergerによりmanifestファイルから統合ファイルを生成する。

こんな感じで行うといいです。

セットアップ

まずswagger-mergerとはnode.js製のcliツールで、npmを使ってinstallします。

そのため、ホスト環境を汚したくない場合はdockerやvagrantなどで仮想環境を用意し、その中で作業を行いましょう。

    1. npmが入っていない場合はinstall
    2. npmを使ってswagger-mergerをinstall (別にglobal installじゃなくてもよし)
    3. npm install swagger-merger -g

運用方法

まずcomponentやpathごとに分割したymlファイルを作成します

次に、manifestファイルを作成(名前はopenapi_manifest.ymlなど)し、referencesを書き込んでいきます

最後に、swagger-mergerを使い、manifestファイルから統合ファイル(openapi.yml)をbuildします

swagger-merger -i openapi_manifest.yml -o openapi.yml

※-oで出力ファイルの名前を指定しないとデフォルトではswagger.ymlという名前のファイルが生成されるが、これはopenapi 3.0ではうまく動かないので注意(ファイル名のprefixにopenapiをつけないといけないっぽい)

統合ファイルの出力もCIに組み込んだりgit hookで引っ掛けたりして、できれば人力でなく自動で行うといいですね。

参考

swagger-merger
Merge multiple swagger files into a swagger file, support JSON/YAML.

コメント

タイトルとURLをコピーしました