Overview

業務で利用してる OpenAPI3 に置いて、Endpoint の定義間（api と admin みたいな）で共有したいコンポーネントがあり、それを外部ファイルに定義したときに、各定義で参照する方法を調べたので備忘録として記載します。

やり方

$ref にファイルパスを渡す。

至って簡単です。

例えば　JSON Schema を利用していてファイル構成が以下のような場合

└ api.json
└ admin.json
└ component/
         └ common.json

JSON ファイル側で $ref に component に切った json のファイルパスと定義までのドキュメントのパスを指定します。

つまり以下のようになります。

定義側

// common.json

{
    "components: {
        "schemas": {
            "SampleComponent": {...}
        }
    }
}

参照側

{
    "$ref": "component/common.json#components/schemas/SampleComponent"
}

これで参照できるようになります。案外簡単でした。