Akira

Posted on Jun 2 • Originally published at apidog.com

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

OpenAPI仕様はAPIの契約です。仕様が実装とずれると、クライアントは壊れ、モックは古くなり、存在しないAPIに対してテストが通ってしまいます。だからこそ、openapi.yamlはコードと同じようにGitで管理し、ブランチを切り、レビューし、変更ごとに検証する必要があります。

Apidogを今すぐ試す

この記事では、OpenAPI仕様をGitでバージョン管理するための実装手順を整理します。仕様ファイルの配置、ブランチ戦略、PRレビューで見るべきポイント、CIでの検証、ApidogからGitへ変更をプッシュする流れまでを扱います。

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

Wikiや共有ドライブに置かれた仕様は、変更履歴を追いにくくなります。たとえば、誰がいつ POST /orders のリクエストボディを変更したのか、その変更理由まで確認するのは困難です。

openapi.yaml をGit管理すると、次のことができます。

履歴を残す

すべての変更をコミットとして記録できます。
変更者を追跡する

git blame openapi.yaml で、特定のフィールドを誰が追加・変更したか確認できます。
ロールバックする

契約を壊す変更がマージされた場合でも、コミットを戻せます。
レビューする

仕様変更をPull Request経由にすることで、リリース前に差分を確認できます。

これは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の中心です。

重要なのは、チームで1つの規約を決めて文書化することです。「正しい仕様」とされるファイルが複数存在する状態は避けてください。

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

仕様専用の複雑なブランチモデルは不要です。通常のコード変更と同じように、main からブランチを切り、変更し、Pull Requestを作成します。

ブランチ名には、仕様変更だと分かるプレフィックスを付けます。

ブランチタイプ	パターン	例
新規エンドポイント	`api/add-<resource>`	`api/add-refunds`
フィールド変更	`api/change-<resource>-<field>`	`api/change-order-status`
破壊的変更	`api/breaking-<description>`	`api/breaking-v2-auth`
修正 / クリーンアップ	`api/fix-<description>`	`api/fix-pagination-schema`

api/ プレフィックスを付けると、このPRがAPI契約に関係することが一目で分かります。レビュー担当者やCIも、このプレフィックスを使って対象を判定できます。

破壊的変更には breaking- を含めます。これにより、追加レビューやメジャーバージョン更新が必要な変更として扱いやすくなります。

ブランチは短命にしてください。仕様変更ブランチが長期間残ると、他の変更と競合しやすくなります。1つのブランチでは、1つの論理的な仕様変更だけを扱うのが基本です。

Pull Requestで仕様変更をレビューする

OpenAPI仕様のPRは、API契約の変更です。通常のコードレビューと同じく、差分を確認し、互換性を判断します。

まず、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つのプロパティを書く
不要な並べ替えを避ける
フォーマッタをチームで統一する

レビュー担当者は、主に次を確認します。

破壊的変更がないか

必須リクエストフィールドの追加、レスポンスフィールドの削除・リネーム、Enum値の削除など。
後方互換性があるか

新しい任意フィールドや新規エンドポイントは比較的安全です。既存スキーマの変更は慎重に確認します。
命名が一貫しているか

エンドポイント名、複数形、フィールド名、大文字小文字が既存APIと揃っているか確認します。
定義が完全か

新しい操作には summary、レスポンススキーマ、エラー応答を含めます。
例が現実的か

実用的なサンプルは、ドキュメント、モック、テストの品質を上げます。

破壊的変更の検出は、目視だけに頼らないでください。CIで main の仕様とPRの仕様を比較し、互換性のない変更があれば失敗させます。

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

YAMLを直接編集しても構いませんが、ライブバリデーション付きのビジュアルエディタを使うと、入力ミスや構造エラーを早く発見できます。

ApidogのSpec-Firstモードでは、Gitとの双方向同期を使って、UI上で仕様を編集し、変更をコミットしてリポジトリへプッシュできます。チームメイトの変更も同じ方法でプルできます。

基本的な流れは次のとおりです。

Gitリポジトリを接続する
Apidogに仕様ファイルを指定する
ビジュアルエディタでエンドポイント、スキーマ、例を編集する
ApidogがYAMLへ書き戻す
ブランチにコミットしてプッシュする
通常どおりPull Requestを作成する

ApidogはYAMLを一貫した形式で書き出すため、差分を小さく保ちやすくなります。ノイズの多い再フォーマットを避けられるため、レビューでは本質的な仕様変更に集中できます。

設定手順はApidog Spec-First Modeドキュメントで確認できます。GitHubに仕様を同期したい場合は、GitHubへのOpenAPI仕様の同期も参考になります。

CIでOpenAPI仕様を検証する

無効な仕様を main にマージしないように、Pull RequestのCIで検証します。

最小構成の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として正しくパースできるか検証する
スタイルルールに違反していないかLintする
main の仕様とPRの仕様を比較する
破壊的変更を検出したらビルドを失敗させる

CIに入れておくと、人間が見落としやすいエラーを自動で検出できます。

ベストプラクティス

OpenAPI仕様をGitで管理する場合は、次のルールをチームで徹底します。

セマンティックバージョニングを使う

info.version を更新します。破壊的変更はメジャーバージョン、後方互換性のある追加はマイナーバージョンとして扱います。
変更ログを残す

仕様ファイルの近くに CHANGELOG.md を置き、バージョン間の変更点を記録します。
小さなPRにする

1つのPRでは1つの論理的な変更だけを扱います。大きな仕様PRは、破壊的変更を見落としやすくします。
コミットメッセージを具体的に書く

仕様を更新 よりも、返金リクエストに refundReason を追加 のように書きます。
mainを直接編集しない

タイポ修正でもブランチを切り、PRを通します。

よくある質問

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

CIで、Pull Requestの仕様を main の仕様と比較する差分ツールを実行します。

たとえば oasdiff のようなツールを使うと、変更を破壊的、非破壊的、未分類に分類できます。破壊的変更がある場合にビルドを失敗させれば、削除されたフィールド、新しい必須パラメータ、変更された型などを自動で検出できます。

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

まずは単一の openapi.yaml から始めるのがおすすめです。レビューしやすく、バージョン管理もしやすいためです。

ファイルが大きくなった場合や、複数のメジャーバージョンを並行して管理する場合は、次のように分割します。

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

または、$ref を使ってスキーマを別ファイルに分けます。ただし、早すぎる分割は避けてください。読みやすい1つのファイルは、分断された複数ファイルより扱いやすいことがあります。

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

はい。ApidogのSpec-Firstモードでは、ビジュアルエディタで仕様を編集し、変更をGitと双方向に同期できます。

YAMLは一貫した形式で書き出されるため、差分をクリーンに保ちやすくなります。同時に、Git履歴、ブランチ、Pull Requestレビューもそのまま利用できます。

DEV Community