OpenAPIの変更レビュー｜破壊的変更を防ぐ5項目

はじめに

OpenAPIの差分に「追加が中心だから安全」と書かれていても、利用側が止まらないとは限らない。任意項目を必須にする、列挙値を増やす、成功レスポンスを変える、必要な権限を追加する。どれも変更行は小さいが、既存クライアントには大きな影響を与え得る。

OpenAPI Specification（OAS）は、HTTP APIを言語に依存せず記述する標準である。パス、操作、パラメータ、リクエスト、レスポンス、セキュリティを構造化でき、ドキュメント生成やコード生成、テストにも利用できる。一方、OASの文法に合っていることと、既存利用者との互換性が保たれていることは別問題だ。

本記事では、OpenAPIの変更レビューを5項目に分ける。対象は仕様ファイルだけではない。仕様差分を起点に、利用側の実装、データ、権限、移行計画まで確認する。

OpenAPIの変更レビューは「行」ではなく「契約」を見る

YAMLの差分だけを見ると、レビューは追加・削除・型変更の確認で終わりやすい。しかしAPIは、提供側と利用側の契約である。API仕様書の書き方｜5つの契約で整理したとおり、URLと入出力だけでなく、認証、エラー、再試行、変更管理まで合意して初めて実装に渡せる。

OpenAPI 3.1.1では、Operation Objectにparameters、requestBody、responses、securityなどを記述できる。Schema ObjectはJSON Schemaの語彙を利用し、型、必須項目、許容値などを表現できる。つまり差分には、単なる文章変更ではなく、利用側が守る契約の変更が含まれる。

レビューの入口では、変更を次の3つに分類する。

「追加だから互換」と自動判定しないことが重要だ。未知の項目を拒否するデシリアライザーや、列挙値を網羅した分岐は、追加でも停止する可能性がある。

破壊的変更を防ぐ5つの確認項目

1. パスと操作：呼び出し先とHTTPの意味が変わらないか

最初に確認するのはpaths配下だ。パスの削除やHTTPメソッドの変更は分かりやすい非互換変更だが、operationId、パスパラメータ、ステータスコードの変更も影響が大きい。

特に、コード生成を使うクライアントではoperationIdがメソッド名に反映される場合がある。サーバーのURLが変わらなくても、operationIdの変更だけで再生成後にビルドが通らなくなることがある。

HTTPメソッドの意味も確認する。RFC 9110はGET、HEAD、OPTIONS、TRACEをsafe methodとして定義し、PUT、DELETEとsafe methodをidempotentと定義している。これは「必ず副作用がない」「失敗しない」という意味ではない。利用者が要求した意味と、同じ要求を複数回送ったときの意図された効果に関する性質だ。

レビューでは次を問う。

• 既存パスや操作が削除・改名されていないか
• path parameterの名前、型、必須性が変わっていないか
• operationId変更が生成コードへ影響しないか
• GETを更新処理に使うなど、HTTPの意味が崩れていないか
• 再試行可能性や冪等性の前提が変わっていないか

API Gatewayの設定やルーティング、監視ルールも同じパスを参照する。アプリコードだけでなく、運用設定の利用箇所も影響範囲に含める。

2. 入力：必須条件と許容範囲が狭くなっていないか

入力側では「既存の正しい要求が、新仕様で拒否されないか」を見る。代表的な非互換変更は、任意項目の必須化、型変更、最大長の短縮、最小値の引き上げ、許容値の削除だ。

たとえば顧客登録APIでphoneをrequiredへ追加すると、新しい画面は対応できても、旧バッチや外部連携は400エラーになる。文字列の最大長を100から50へ短縮する変更も、既存データを再送する処理で初めて障害になる場合がある。

確認対象はschemaだけではない。

• requestBodyのrequired化
• query、header、cookie parameterの追加と必須化
• enum、pattern、minimum、maximum、maxLengthの変更
• nullの許可・不許可
• default値や省略時動作の変更
• Content-Typeとエンコーディングの変更

入力制約を強くしたい場合は、いきなり拒否するより段階を分ける。まず警告と利用状況の計測を入れ、違反しているクライアントを特定し、修正期間を確保してから制約を強制する。仕様の変更日だけでなく、強制開始日も管理する。

3. 出力：利用側の読み方を壊していないか

出力側は「新しいレスポンスを、古い利用側が読めるか」を見る。項目削除、名前変更、型変更、必須項目の欠落は典型的な非互換変更である。

注意したいのが、提供側では安全に見える追加だ。レスポンス項目の追加は通常扱いやすいが、未知項目を拒否する利用側では失敗する。enumへの値追加も、switch文が既知値だけを処理し、defaultで例外を投げる実装なら破壊的だ。

さらに、HTTPステータスとエラー形式を確認する。成功を200から202へ変えれば、同期完了を前提にしていた利用側は状態確認処理が必要になる。404を200と空配列へ変える変更も、業務上の「対象なし」の扱いを変える。

レビューでは、正常系と異常系を同じ重さで比較する。

AI要件定義で最初に作るテストケースで扱うように、正常系だけでなく判断分岐や停止条件も先に定める。APIの変更要求から契約テストまで追跡できる形にする。サンプルJSONの目視確認だけでは、境界値や未知値の扱いが抜ける。

4. 認証と権限：接続できても実行できるか

securitySchemesやoperationごとのsecurity変更は、データ型の差分より見落とされやすい。認証方式の変更、OAuthスコープの追加、APIキーの送信場所変更は、既存クライアントを即座に止める可能性がある。

ただし、OpenAPIに書かれるsecurityだけでは業務権限を表し切れない。たとえば「expense.writeスコープを持つ部門長は、自部門の申請だけ承認できる」という条件では、スコープに加えてデータ範囲の判定が必要だ。

次の4点を分けてレビューする。

1. 誰として認証するか
2. どの操作を許可するか
3. どのデータ範囲を扱えるか
4. 誰の権限で実行したかを何に残すか

権限強化が必要でも、旧方式を予告なく止めてはいけない。新旧認証の並行期間、資格情報の切り替え手順、失敗率の監視、ロールバック条件を決める。セキュリティ向上と移行可能性を同時に満たす設計が必要だ。

5. 移行と版：いつ誰が何を変えるか決まっているか

互換性判定の最後は、変更をどう届けるかである。SemVer 2.0.0は、公開APIに後方互換性のない変更を含む場合はメジャーバージョンを上げ、後方互換性を保った機能追加はマイナー、後方互換性を保ったバグ修正はパッチとする。ただし版番号を上げるだけでは、API利用者は移行できない。

最低限、次を変更記録に持たせる。

• 変更理由と要求ID
• 互換性区分と判定根拠
• 影響するクライアントと責任者
• 新旧版の並行稼働期間
• 移行手順と検証方法
• 利用状況を測る指標
• 廃止日とロールバック条件

URLにv2を付ければ解決するわけでもない。旧版をいつまで保守するのか、データ更新が両版で整合するのか、障害時にどちらへ戻すのかが必要だ。版はラベル、移行計画は実行条件である。

実務で使える変更レビュー表

Pull Requestには、OpenAPI差分と一緒に次の表を置くと判断しやすい。

レビューの完了条件は「差分を見た」ではない。影響する利用者が特定され、移行手順と契約テストがあり、リリース後に確認する指標まで決まっていることだ。AIコードレビューのやり方｜7つの確認点と同じく、AIや差分ツールは候補抽出に向くが、業務上の互換性と移行可否は当事者が判断する。

まとめ：OpenAPI差分をリリース判断へつなげる

OpenAPIの変更レビューでは、次の5項目を順に確認する。

1. パスと操作
2. 入力の必須条件と許容範囲
3. 出力とエラーの読み方
4. 認証・操作権限・データ範囲
5. 版、移行、廃止、ロールバック

仕様の構文検証は必要だが、それだけでは破壊的変更を防げない。差分を契約として読み、既存クライアントのテストと移行計画へつなげて初めて、安全なリリース判断になる。

株式会社Atsumellでは、業務要件からAPI、データ、権限、例外、受け入れ条件まで、実装に渡せる仕様づくりを支援している。業務フローと仕様の整理には、Kakusillの紹介も参考にしてほしい。API変更の影響が担当者の経験だけに依存している場合は、お問い合わせから相談してほしい。

参考資料

• OpenAPI Specification v3.1.1
• RFC 9110: HTTP Semantics
• セマンティック バージョニング 2.0.0