AWSの話題を中心に、日々の業務やプログラミングの徒然を綴るエンジニアブログです。

HANDS LAB

HANDS LAB ENGINEERS BLOG

ハンズラボエンジニアブログ

Swaggerで作るSPECファイルを小さいファイルに分割する


こんにちは、井上です。

Swaggerで始めるモデルファーストなAPI開発」を見て興味を持ったので、Swaggerをちょっと触ってみたのですが、すぐに、これ1ファイルの YAMLファイルでメンテナンスするの超しんどくない?と感じました。

なので、分割する方法を調べてみました。で、みつけたのが下記エントリ。
How to split a Swagger spec into smaller files

方法としては、別々のファイルに書いた定義を $ref で参照しておき、それを json-refs でマージして1ファイルに戻すというやり方のようです。

下記のような YAML ファイルを、

下記のように分割します。

起点となる index.yaml は下記のようにリンク集のような形になります。

サンプルが githubに上がっているので、それで試してみます。

全部マージして出力されました。

JSON形式になっていますが、resolve.js を下記のような感じに変更すると、YAML 形式で出力されます。
※ js-yaml が必要なので、別途 npm install js-yaml が必要です。

オプションに、resolveLocalRefs: false を加えると、ファイル内の $ref: ‘#/definitions/User’ は展開されず、別ファイルのみ展開されます。
同じ定義を繰り返し参照しているような場合には、展開しないほうが見通しが良いと思います。

使用できるオプションは、下記で参照できます。
json-refs/API.md at master · whitlockjc/json-refs


投稿者:

Taiji Inoue

こんにちは!