こんにちは！ニーリーアドベントカレンダー2025の17日目はプラットフォーム開発チームの松村からお届けします。
直近、プラットフォーム開発チームでは複数のビジネスプロダクトから利用される会員・決済といった共通基盤機能を提供するプロダクトを開発するためのエコシステム整備を進めています。 そんな中で出会った Redocly CLI が OpenAPI 定義を管理するツールとして素敵そうにみえたので今回はその話をしていきます。
なぜOpenAPI？
これから構築していく共通基盤機能は主にWeb APIの形式で提供していきます。 そんな中、エコシステムの整備において用意したいものの一つに「APIドキュメント・カタログを用意する仕組み」が上がりました。 共通基盤なプロダクトを作る上で大切なのはスケールのためのセルフサービス化だと思っており、 エンジニアが自力で欲しいAPIを探し出してその仕様を把握できるようドキュメントは整備しておきたいと考えました。
API仕様を管理する主流な技術の一つにOpenAPIがあります。 OpenAPIはWeb APIの形式的・機械可読なフォーマットとして広く使われており、周辺のツールも豊富です。 Swagger UIやRedocなど、OpenAPIからAPI仕様ドキュメントを生成してWebでホスティングできるようなツールも充実しています。 その他にも、形式的な定義があることで様々な自動化の可能性が広がります。 例えば、OpenAPI定義からMCPサーバーを自動生成するといった構想も可能です。
そんなわけで、今回は共通基盤プロダクト開発のエコシステム整備の一環でOpenAPI定義を管理する仕組みを検討することにしました。
OpenAPIの定義管理で欲しかったもの
OpenAPIの定義を管理していく上で、欲しいと思ったものは2つあります。
1つ目は OpenAPI定義のバリデーションです。 何かを管理・保守していくならCIによるバリデーションは大切ですよね。 ドキュメントの更新をはじめ様々なものを自動化するなら、それらが動かない状態のものがマージされるのは防ぎたいです。 おかしなものがビルドされてしまうのも困りますし、作業後に気づいて修正しなければならないのも手戻りが多くて大変です。 定義が壊れていないかをレビューでチェックするのは困難なので、形式的に定義が決まっているものなら機械的にチェックをかけたいなと思いました。
2つ目はOpenAPI定義を分割管理するための仕組みです。
APIの数が増えてくるとOpenAPI定義ファイルはどんどん肥大化していき、編集するのも大変になっていきます。
こういう話をすると、新卒入社した職場の研修で同じチームになったエンジニアが「OpenAPI定義は人が手で書くものじゃない」なんてことを言ってたのを今でも思い出しますね（笑）。
特に今回は共通基盤の複数のプロダクトを束ねて扱うことになるので、より管理が大変になることが予想されます。
OpenAPIは $ref による定義の分割定義をサポートしています。
基本的にはこれを活用して定義を分割して管理するケースが多いと思いますが、一方でツールによっては単一の定義ファイルでないと利用できないものもあったりします。
というわけで、普段は $ref で定義を分割管理しつつ、必要に応じて定義をマージして単一の定義ファイルを扱えるようにしたいというニーズがありました。
Redocly CLIとは
そんな中で見つけたのが Redocly CLIでした。
Redocly CLIは、API定義管理SaaSであるRedoclyから提供されているOpenAPI管理のための諸機能を詰め込んだCLIツールです。 先ほど触れた Redoc はredoclyのドキュメント生成機能がOSSとして公開されているものです。 Redocly CLIも同様にOSSとして公開されており、Redoclyの契約をしていなくても利用することができます。
Redocly CLIを使えば、巨大な定義ファイルの分割管理やそのマージを扱うことができます。 バリデーション機能もその前提で用意されており、分割されたファイルをサポートしているのも嬉しいポイントです。 また、SaaSに付帯するツールという立ち位置なため、コミュニティの大きさやドキュメンテーション、メンテナンスの継続に関しても信頼できるというのもメリットです。
以上の理由から、今回はOpenAPI定義管理のためのツールをRedocly CLIに寄せていくことにしました。
機能の紹介
Redocly CLI には充実した利用マニュアルがありますが、せっかくなので今回利用した機能を中心にその使い方を紹介します。
バリデーション
redocly lint <定義ファイル名>
でバリデーション・リントを実行できます。
先述の通りファイル分割に対応しており、その場合はエントリーポイントとなるファイルを指定するだけで $ref をうまく扱ってくれます。
バリデーション項目は設定ファイルで調整することができます。 プロジェクトルートに設定ファイルを書いておくと、プロジェクト全体でその設定を参照してくれます。 ルールの設定にはいくつかのプリセットがあり、そこから個別のルールを追加したり無効化したりしてカスタマイズができます。 詳細についてはこちらのページで説明されています。
以下が設定ファイルの例です。この例では、spec をベースに spec-strict-refs のみチェックを切るよう設定しています。
extends: - spec rules: spec-strict-refs: off
extends にはベースとなるプリセットを指定します。プリセットは以下のものが用意されています。
| プリセット | 概要 |
|---|---|
spec |
OpenAPI定義に則しているかをチェックする |
recommended |
redocly が推奨するAPIのプラクティスに則しているかをチェックする |
recommended-strict |
recommended で warning 扱いだったルールを error に厳格化したもの |
minimal |
error 扱いの項目を可能な限り減らした最小限のルールセット |
rules 以下でルールごとにプリセットのSeverityを上書きすることで調整が可能です。
| Severity | 概要 |
|---|---|
error |
エラーメッセージを出力して、バリデーションを失敗させる |
warn |
エラーメッセージのみ出力して、バリデーションを失敗させない |
off |
ルールを無効化してスキップする |
定義のマージ
redocly bundle <エントリーポイントの定義ファイル名> -o <出力先ファイル名>
で分割したファイルのマージを行うことができます。 ファイル名の指定を省くと、標準出力に出力されます。
例えば以下のような感じでOpenAPI定義を分割していたとします。
root.yaml：
openapi: "3.0.1" info: title: Your Beautiful API version: 1.0.0 paths: /foo/v1/xxx: $ref: "./services/foo/foo.yaml#/paths/~1foo~1v1~1xxx" /bar/v1/yyy/{id}: $ref: "./services/bar/bar.yaml#/paths/~1bar~1v1~1yyy~1{id}"
foo.yaml：
openapi: "3.0.1" info: title: Foo Service API Definition version: 1.0.0 paths: /foo/v1/xxx: get: responses: "200": description: "200 OK" content: "application/json": schema: type: object properties: results: type: array items: $ref: "./components/schema/xxx.yaml" post: ...
bar.yaml：
openapi: "3.0.1" info: title: Bar Service API Definition version: 1.0.0 paths: /bar/v1/yyy/{id}: get: ...
redocly bundle を使えば、これをマージして以下のような定義を生成できます。
openapi: 3.0.1 info: title: Your Beautiful API version: 1.0.0 paths: /foo/v1/xxx: get: responses: '200': description: 200 OK content: application/json: schema: type: object properties: results: type: array items: $ref: '#/components/schemas/xxx' post: ... /bar/v1/yyy/{id}: get: ... components: schemas: xxx: ... ...
その他
まだ試せてはいないですが、Redocly CLIには便利そうな機能が他にもあります。
redocly split は bundle とは逆に一つの定義ファイルを分割する機能です。
実行すると、一つの定義ファイルを以下のように分割してくれるみたいです。
| 生成物 | 内容 |
|---|---|
openapi.yaml |
エントリーポイントとなるOpenAPI定義 |
paths/ |
パスごとに分割されたAPI定義群 |
components/ |
components セクションにある各定義を分割したファイル群 |
OpenAPI定義を編集する際にGUIツールを使いたいという方もいると思います。 これを活用すれば一時的に手元でマージした定義をツールで編集した後、 それを分割したもので更新をかけるといった運用も実現できるでしょう。
また、Configurable rulesというバリデーションのルールを自作してカスタマイズできる機能も提供されています。
OpenAPIには x- から始まるキーで定義を拡張できるという仕様があります。
例えば、AWS API Gatewayはこの仕様を利用して設定に用いる値をOpenAPI定義中に記述できるようにしています。
こうしたサードパーティの項目や、自動化のために独自定義した項目に対するバリデーションを作り込むこともこのカスタマイズを活用すれば可能そうです。
おしまい
というわけでOpenAPI定義の管理ツールであるRedocly CLIを紹介しました。 上手く使えば大規模なOpenAPI定義でも快適に保守・管理できそうな気がしますね！
こんな感じで、現在ニーリーではマルチプロダクト化に向けて共通基盤プロダクト開発の足回りを整備している真っ最中です。 ニーリーにおける共通基盤プロダクト開発の面白さ・展望について書いた以下の記事もありますので、興味があれば合わせて読んでもらえるとすごく嬉しいです。
