GitでOpenAPI仕様をバージョン管理する方法

OpenAPI仕様は契約書です。それがずれてしまうと、クライアントは機能しなくなり、モックは古くなり、存在しないAPIに対してテストがパスしてしまいます。そのため、仕様は他のコードと同じように扱いましょう。Gitに入れ、ブランチを切って、レビューし、変更ごとに検証してください。

このガイドでは、OpenAPIのバージョン管理をGitで行う方法を基礎から解説します。ファイルがどこに置かれるべきか、どのようにブランチを切るか、レビュー担当者が仕様の差分で実際に何を確認するか、そしてApidogから直接変更をプッシュする方法まで。読み終える頃には、チーム全体が信頼できるワークフローを身につけているでしょう。

OpenAPI仕様をバージョン管理する理由

Wikiや共有ドライブにある仕様には履歴がありません。先週の火曜日に誰がPOST /ordersのペイロードを変更したのか、その理由も分かりません。Gitはそれを解決します。

openapi.yamlをバージョン管理下に置くと、次の4つのメリットが無料で得られます。

• 履歴。すべての変更は、作成者、タイムスタンプ、メッセージを含むコミットとして記録されます。
• Blame（責任追跡）。git blame openapi.yamlを実行すると、誰がその必須フィールドをいつ追加したかがわかります。
• ロールバック。契約を壊したマージがあった場合、コミットを元に戻せば、動作する仕様に戻せます。
• レビュー。仕様の変更はプルリクエストを介して行われるため、リリースされる前に別の人が差分を確認できます。

これはGitネイティブなAPIワークフローの基盤です。仕様はソースコードであり、ソースコードはGitにあります。

リポジトリ内で仕様ファイルが置かれる場所

シンプルで予測可能に保ちましょう。ほとんどのチームは、単一のopenapi.yamlをリポジトリのルート、またはapi/フォルダに置きます。

my-service/
├── api/
│ └── openapi.yaml
├── src/
└── README.md

複数のメジャーバージョンを並行して管理する場合は、メジャーバージョンごとにファイルを分割します。

api/
├── api-v1.yaml
└── api-v2.yaml

これにより、破壊的変更が分離されます。api-v1.yamlは既存のクライアントのために固定され、api-v2.yamlは進化します。また、各ファイルが単一の理由で変更されるため、差分が小さくなり、レビューが速くなります。このように仕様を扱うことが、API Spec as Codeの核心的な考え方です。

一つの規約を選び、それを文書化してください。最悪の結末は、「その」仕様であると主張するファイルが2つ存在することです。

仕様変更のためのブランチ戦略

仕様のために特別なブランチモデルは必要ありません。既存のコードで使っているものを再利用しましょう。mainからブランチを切り、変更を行い、PRを開きます。

仕様ブランチを見つけやすくする命名規則：

api/というプレフィックスは、「このPRは契約に触れるものだ」と一目でわかります。レビュー担当者やCIはそれでフィルタリングできます。破壊的変更の場合、明示的なbreaking-プレフィックスは、追加の確認と、おそらくバージョンアップが必要であることを示すフラグとなります。

ブランチは短命に保ちましょう。2週間も生き残る仕様ブランチは、他の全員の変更と衝突するでしょう。小さく集中したブランチはきれいにマージされます。

プルリクエストでの仕様変更のレビュー

ここがバージョン管理の真価が発揮される場所です。仕様のPRは契約の変更であり、契約の変更は真剣なレビューに値します。

レビュー担当者がフォーマットと格闘するのではなく、変更内容を読めるように、差分に優しい方法でYAMLを記述してください。

paths:
 /orders/{orderId}:
 get:
 summary: 注文を取得
 parameters:
 - name: orderId
 in: path
 required: true
 schema:
 type: string
 responses:
 "200":
 description: 注文が見つかりました
 content:
 application/json:
 schema:
 $ref: "#/components/schemas/Order"

一貫したインデントと、1行に1つのプロパティを記述することで、単一フィールドの追加が1行の差分として表示されます。それが目標です。

レビュー担当者が確認すべき点：

• 破壊的変更。リクエストに必須フィールドが追加されましたか？応答フィールドが削除または名前変更されましたか？Enumが値を失いましたか？これらはそれぞれ既存のクライアントを壊す可能性があります。
• 下位互換性。新しいオプションフィールドと新しいエンドポイントは安全です。既存の形状への変更は安全ではありません。
• 命名と一貫性。新しいエンドポイントは、APIの他の部分の大文字・小文字の区別と複数形に合致していますか？
• 完全性。すべての新しい操作には、summary、応答スキーマ、およびエラー応答が必要です。
• 例。現実的な例は、ドキュメントとモックを役に立つものにします。

破壊的変更の検出には、目視ではなくツールに頼りましょう。CIステップ（後述）で、PRの仕様をmainと比較し、互換性のない変更を見つけた場合はビルドを失敗させることができます。人間は見落としますが、差分ツールは見落としません。

Apidogからコミット＆プッシュ

生のYAMLを手作業で編集することも可能ですが、ライブバリデーションを備えたビジュアルエディタの方が高速で、より早く間違いを発見できます。ApidogのSpec-Firstモードは、双方向のGit同期を提供します。ツールを離れることなく、UIで仕様を編集し、コミットしてリポジトリにプッシュできます。チームメイトの変更を同じ方法でプルすることも可能です。

ワークフローは次のようになります。

1. Gitリポジトリを接続し、Apidogに仕様ファイルを指定します。
2. ビジュアルエディタでエンドポイント、スキーマ、および例を編集します。
3. Apidogはクリーンで差分に優しいYAMLをファイルに書き戻します。
4. ブランチでコミットしてプッシュし、通常通りPRを開きます。

ApidogはYAMLを一貫してシリアル化するため、差分は小さく、レビューしやすく保たれ、ノイズの多い並べ替えや再フォーマットは発生しません。完全な設定については、Apidog Spec-First Modeドキュメントで確認できます。特定のプロバイダにファイルを連携したい場合は、GitHubへのOpenAPI仕様の同期を参照してください。

CIバリデーションフック

無効な仕様をmainに到達させてはいけません。プルリクエストチェックにバリデーションを組み込み、壊れた契約は自動的にビルドを失敗させるようにしましょう。

最小限のGitHub Actionsステップ：

name: Validate OpenAPI
on: [pull_request]
jobs:
 lint:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 - name: Lint spec
 run: npx @redocly/cli lint api/openapi.yaml

成長に合わせて、さらに多くのチェックを追加してください。

• 構造的およびスタイル上の問題について仕様をLintする。
• OpenAPI 3.xとして正しくパースされることを検証する。
• mainと比較して破壊的変更を検出し、PR上でフラグを立てる。

これらのチェックは数秒で実行され、人間が見落としがちなエラーをキャッチします。

ベストプラクティス

いくつかの習慣が、仕様のバージョン管理を健全に保ちます。

• セマンティックバージョニングを使用する。info.versionフィールドを更新します。破壊的変更はメジャーバージョンアップを意味し、後方互換性のある追加はマイナーバージョンアップを意味します。
• 変更ログを保持する。仕様の隣に短いCHANGELOG.mdを置くことで、どのバージョン間で何が変更されたかを消費者に伝えます。
• 小さな差分をリリースする。1つのPRにつき1つの論理的な変更のみ。大きな仕様PRは、ノイズの中に破壊的変更を隠してしまいます。
• 記述的なコミットメッセージを作成する。「返金リクエストにrefundReasonを追加」は、「仕様を更新」よりも優れています。
• main上でマージされた仕様を直接編集しない。タイプミスであっても、常にブランチを切ります。

よくある質問

OpenAPI仕様における破壊的変更を検出するにはどうすればよいですか？

CIで、プルリクエストのバージョンをmainのバージョンと比較する仕様差分ツールを実行します。oasdiffのようなツールは、各変更を破壊的、非破壊的、または未分類に分類し、破壊的な変更があった場合にビルドを失敗させることができます。これにより、手動レビューでは見落としがちな、削除されたフィールド、新しい必須パラメータ、変更された型などを検出できます。

OpenAPIファイルを1つにまとめるべきですか、それとも複数に分割すべきですか？

まずは単一のopenapi.yamlから始めましょう。これが最もレビューしやすく、バージョン管理しやすいです。ファイルが大きくなったり、複数のメジャーバージョンを並行して管理したりする場合は、メジャーバージョンごとに分割（api-v1.yaml、api-v2.yaml）するか、$refを使用してスキーマを別々のファイルに分割します。時期尚早な分割は避けましょう。読みやすい1つのファイルは、断片化された5つのファイルよりも優れています。

YAMLを手書きせずに仕様をバージョン管理できますか？

はい、可能です。ApidogのSpec-Firstモードでは、ビジュアルエディタで仕様を編集し、変更を双方向にGitに同期できます。一貫したYAMLを書き出すため、差分はクリーンに保たれ、プルリクエストは読みやすくなります。同時に、完全なGit履歴とレビューも得られます。