大規模なウェブサービスを作っていると、WebAPIの数も膨大になってきます。APIのドキュメントを作成するためにOpenAPIを使っている人も多いと思いますが、APIの数が増えてくるとドキュメントのソースファイル（JSON/YAML）が大きくなり、編集しづらくなります。
でかいソースファイルは分割するのが世の常で、もちろんOpenAPIにもソースファイルを分割できる仕様はあるのですが（文法はJSON
Schemaなので）、問題は分割したファイル（$refによる参照先のファイル）にIDEのコード補完が利かなくなることです。
そこで、ソースファイルを分割しつつ、IDEのコード補完も利かせる方法を考えてみます。IDEはウェブ開発の定番Visual Studio Codeを想定します。え？VSCodeはIDEじゃない？気にするな。
なお、この記事は「OpenAPIのドキュメントの書き方を知っていること」「ソースファイルの分割方法（$ref）を知っていること」「VSCodeのOpenAPI拡張機能を使っていること」を前提としています。その上で、分割したファイルの補完を使う方法の説明です。