API仕様がApidogにあり、信頼できる情報源がGitにある場合は、両者を同期して「仕様の単一の真実」を維持します。Apidog Git連携を使うと、GitHub、GitLab、Azure DevOpsリポジトリをApidogプロジェクトに接続し、OpenAPI仕様をGitへプッシュしたり、Git側の変更をApidogへプルしたりできます。結果として、仕様変更の監査証跡、コードレビュー、バックアップをGit上に残せます。
この記事では、Apidog Git連携でできること、対応プロバイダー、双方向同期と自動バックアップの違い、ブランチ設計、権限管理、競合対応までを実装手順ベースで整理します。GitHubに絞った手順が必要な場合は、OpenAPI仕様をGitHubに同期する方法も参照してください。
Apidog Git連携でできること
Apidogは、Gitと2つの方法で連携します。まずこの違いを理解しておくと、設計と運用を決めやすくなります。
| 機能 | 方向 | トリガー | 主な用途 |
|---|---|---|---|
| Spec-Firstモード同期 | 双方向：Apidog ↔ Git | 手動コミット、プッシュ、プル | OpenAPI仕様をコードとして管理し、PRレビューしたいチーム |
| 自動Gitバックアップ | 一方向：Apidog → Git | スケジュール実行 | 日常ワークフローを変えずに、仕様の履歴とバックアップを残したいチーム |
1. Spec-Firstモードによる双方向同期
Spec-Firstモードでは、Apidog上でOpenAPIドキュメントをYAMLまたはJSONとして編集し、その変更をGitへコミット・プッシュできます。
Git側で誰かが仕様を更新した場合は、Apidogへプルして反映できます。つまり、ApidogとGitのどちらも編集元になれる双方向のワークフローです。
2. API仕様の自動Gitバックアップ
自動Gitバックアップでは、Apidogが各モジュールのOpenAPI/Swaggerファイルをスケジュールに基づいてGitリポジトリへエクスポートします。
これは一方向です。Git上の変更をApidogへ読み戻す用途ではありません。履歴保存、監査、復旧用の安全網として使います。
以降では、「同期」はSpec-Firstモードの双方向同期、「バックアップ」は一方向の自動エクスポートを指します。
サポートされているGitプロバイダー
Apidogは、GitHub、GitLab、Azure DevOpsとの連携をサポートしています。
| プロバイダー | 認証方法 | 備考 |
|---|---|---|
| GitHub | OAuth認証 | 個人リポジトリと組織リポジトリに対応。組織リポジトリでは管理者承認が必要な場合があります。 |
| GitLab | OAuth認証 | gitlab.comおよびApidogからアクセス可能な自己管理型GitLabに対応。 |
| Azure DevOps | 汎用Git接続：HTTPS + トークン | HTTPSクローンURLと、リポジトリスコープを持つ個人アクセストークンで接続します。 |
Azure DevOpsは、汎用Git接続を使って接続します。GitHubやGitLab以外のGitホストでも、HTTPSクローンURLとトークン認証に対応していれば、同様の方法で接続できる場合があります。
Gitプロバイダーを接続する
基本的な流れは次のとおりです。
- ApidogでGit連携設定を開く
- Gitプロバイダーを選択する
- 認証する
- リポジトリを選択する
- ブランチを選択する
- 同期またはバックアップ対象を設定する
GitHubを接続する
GitHubの場合はOAuthで認証します。
- ApidogからGitHub接続を開始する
- GitHubのOAuth画面でログインする
- Apidogにリポジトリへのアクセスを許可する
- 対象リポジトリとブランチを選択する
組織リポジトリを使う場合、GitHub組織の設定によっては、管理者がApidogのアクセスを承認する必要があります。認証できたのにリポジトリが表示されない場合は、まず組織側のサードパーティアプリ承認を確認してください。
GitLabを接続する
GitLabもOAuthで接続します。
- ApidogからGitLab接続を開始する
- GitLabのOAuth画面でログインする
- リポジトリへのアクセスを許可する
- 対象リポジトリとブランチを選択する
自己管理型GitLabを使う場合は、ApidogからそのGitLabインスタンスへネットワークアクセスできる必要があります。
Azure DevOpsを接続する
Azure DevOpsでは、汎用Git接続を使います。
必要なものは次の2つです。
- Azure DevOpsリポジトリのHTTPSクローンURL
- コードの読み書き権限を持つ個人アクセストークン、PAT
手順は次のとおりです。
- Azure DevOpsでPATを作成する
- PATに対象リポジトリの読み書き権限を付与する
- Apidogで汎用Git接続を選択する
- HTTPSクローンURLを入力する
- PATを入力する
- リポジトリとブランチを設定する
PATはApidogがGitへプッシュするための資格情報です。フルアクセスのトークンではなく、対象リポジトリに必要な最小権限だけを付与してください。
権限設定で確認すること
Git連携を設定するときは、次の点を確認してください。
- 組織リポジトリでは、管理者承認が必要な場合がある
- Azure DevOpsや汎用Git接続では、PATのスコープを対象リポジトリに限定する
- プライベートリポジトリも利用できる
- プッシュ権限を持つユーザーを限定する
- 認証に使ったユーザーやトークンの権限が、実際のGit操作権限になる
GitによるOpenAPI仕様管理の前提を整理したい場合は、GitによるOpenAPIバージョン管理も参考になります。
Spec-Firstモードで双方向同期する
Spec-Firstモードでは、ApidogをOpenAPI仕様エディタとして使い、Gitへコミット・プッシュできます。詳細はApidog公式ドキュメントを参照してください。
実装フローは次のとおりです。
- ApidogでSpec-Firstモードを有効にする
- Gitリポジトリとブランチを接続する
- OpenAPI YAMLまたはJSONを編集する
- 変更内容を確認する
- コミットメッセージを入力する
- Gitへプッシュする
- Git側の変更がある場合はApidogへプルする
OpenAPI仕様を編集する例
たとえば、注文取得APIを追加する場合は、次のようなOpenAPI YAMLを編集します。
paths:
/v1/orders/{orderId}:
get:
operationId: getOrder
summary: Retrieve a single order
parameters:
- name: orderId
in: path
required: true
schema:
type: string
responses:
'200':
description: The requested order
content:
application/json:
schema:
$ref: '#/components/schemas/Order'
Apidogのエディタでは、シンタックスハイライト、ライブバリデーション、オートコンプリートを使って編集できます。不正な$refや必須フィールドの不足は、プッシュ後ではなく編集時点で検出しやすくなります。
変更をGitへプッシュする
編集後は、通常のGitワークフローと同じように操作します。
- 変更を保存する
- 差分を確認する
- コミットメッセージを書く
- 接続されたブランチへプッシュする
プッシュ後、Apidogの同期状態が最新になっていれば、Apidog上の仕様とGitブランチ上の仕様が一致しています。
Git側の変更をApidogへプルする
チームメンバーがGitリポジトリでOpenAPI仕様を変更した場合は、Apidogへプルします。
これにより、Gitリポジトリが単なるバックアップ先ではなく、Apidogと対等な仕様管理元として機能します。
未プッシュの編集を破棄する
試行錯誤した変更を残したくない場合は、コミット前に未プッシュの編集を破棄できます。
この操作により、作業コピーを最後に同期された状態へ戻せます。不要な実験的変更をGit履歴に残さずに済みます。
このように仕様変更をGitで扱う考え方は、GitネイティブAPIワークフローの中心です。API仕様もコードと同様に、差分レビュー、承認、マージ、ロールバックの対象になります。
API仕様を自動Gitバックアップする
自動Gitバックアップは、Apidog上のAPI仕様をGitへ定期的に保存する機能です。
設定後は、Apidogが各モジュールのOpenAPI/Swaggerファイルを指定したGitリポジトリへ自動的にプッシュします。
対応プロバイダーは次のとおりです。
- GitHub
- GitLab
- Azure DevOps
バックアップは夜間のランダムなオフピーク時間帯に実行されます。これにより、作業時間への影響を抑えながら、Git上に仕様の履歴を残せます。
バックアップで保存されるもの
保存されるのは、各モジュールのエクスポートされたOpenAPI/Swaggerドキュメントです。
Git上では各バックアップがコミットとして残るため、次のような確認ができます。
- 先週のAPI仕様と現在のAPI仕様を比較する
- 特定のフィールドがいつ変更されたか確認する
- 必要に応じて以前の仕様をリポジトリから復元する
バックアップと同期を混同しない
自動Gitバックアップは一方向です。
ApidogはGitへ書き込みますが、Git側の変更をApidogへ読み戻しません。Git側で編集した仕様をApidogへ反映したい場合は、Spec-Firstモードの双方向同期を使います。
ブランチとリポジトリ構成を決める
Git連携を安定運用するには、最初にブランチとリポジトリ構成を決めておくことが重要です。
ブランチ設計
基本方針は次のとおりです。
- 正規の仕様は
mainに置く - 作業中の仕様変更は機能ブランチで行う
- レビュー後にプルリクエストで
mainへマージする
例：
main
feature/add-orders-api
feature/update-user-schema
小規模チームや低リスクの変更では、Apidogを直接mainへ接続する運用も可能です。ただし、レビューゲートを省略することになるため、仕様変更をレビューしたい場合は機能ブランチを使う方が安全です。
リポジトリ構成
代表的な構成は2つです。
APIごとにリポジトリを分ける
orders-api-spec
users-api-spec
billing-api-spec
向いているケース：
- APIごとに所有チームが異なる
- アクセス制御を細かく分けたい
- 各APIの履歴を独立して管理したい
モノレポでまとめる
api-specs/
orders/
openapi.yaml
users/
openapi.yaml
billing/
openapi.yaml
向いているケース：
- プラットフォームチームが複数APIをまとめて管理している
- API横断で検索やレビューをしたい
- 仕様の配置ルールを統一したい
モノレポを使う場合は、モジュールごとに専用ディレクトリを用意してください。バックアップや同期の対象パスが重ならないようにすることで、競合や意図しない上書きを防げます。
チーム権限とアクセスを管理する
Git連携では、権限管理が重要です。確認すべき場所は2つあります。
- Apidog側の権限
- Gitプロバイダー側の権限
Apidog側の権限
Apidogでは、誰が接続済みリポジトリへ同期・プッシュできるかを設定します。
推奨は次の運用です。
- プッシュ権限はAPI仕様のオーナーに限定する
- 閲覧やレビューだけのメンバーには読み取り権限を付与する
- 不要なユーザーに同期操作を許可しない
これにより、仕様を閲覧しているだけのメンバーが誤って変更をプッシュするリスクを下げられます。
Gitプロバイダー側の権限
GitHubとGitLabでは、OAuth認証したユーザーの権限が使われます。
Azure DevOpsや汎用Git接続では、PATが資格情報になります。PATは秘密情報として扱ってください。
実運用では、次のルールを守るのが安全です。
- PATを共有ドキュメントに貼らない
- PATのスコープを対象リポジトリに限定する
- 定期的にトークンをローテーションする
- メンバーが離脱したらトークンを失効する
- 必要に応じてアクティブなアカウントで再認証する
Git連携の安全性は、認証情報の管理に依存します。スコープを狭くし、所有者を明確にしてください。
マージ競合とドリフトに対応する
ApidogはGit履歴へコミットするため、Gitの競合モデルをそのまま扱います。競合は、複数人が同じOpenAPIファイルの同じ箇所を変更したときに発生します。
たとえば、あなたがApidogでOrderスキーマを編集している間に、チームメンバーがGit側で同じOrderスキーマを編集してプッシュした場合、同期時にYAMLのマージ競合が起きる可能性があります。
これはApidog固有の問題ではなく、通常のGitマージ競合です。
競合を減らす運用
競合を減らすには、次の順序を守ります。
- 作業開始前にGit側の最新変更をプルする
- Apidogで仕様を編集する
- 変更をコミットする
- プッシュ前に必要に応じて再度プルする
- 競合がなければプッシュする
競合が起きた場合
競合が発生したら、通常のYAMLマージ競合として解決します。
- 競合している箇所を確認する
- 正しい変更を選択する
- OpenAPIドキュメントとして有効な状態に修正する
- バリデーションを確認する
- 再同期する
Apidogのライブバリデーションは、マージ後のOpenAPI構造が壊れていないか確認するのに役立ちます。
ドリフトを検知する
ApidogとGitリポジトリが徐々に乖離する状態をドリフトと考えます。
同期状態が最新でない場合は、次のどちらかが起きている可能性があります。
- Apidog側に未プッシュの変更がある
- Git側に未プルの変更がある
同期インジケータを確認し、差分が大きくなる前にプルまたはプッシュしてください。
トラブルシューティング
よくある問題は、認証、ブランチ設定、未同期の変更に起因します。
| 症状 | 考えられる原因 | 対処法 |
|---|---|---|
| 認証に失敗する、リポジトリが表示されない | 組織がサードパーティアクセスを承認していない、またはトークンのスコープが不足している | GitHub/GitLabでは組織管理者に承認してもらう。Azure DevOpsでは読み書き権限を持つPATを再発行する。 |
| プッシュが拒否される | トークンが失効または期限切れ、または書き込み権限がない | プロバイダーを再認証する。汎用接続では新しいPATをApidogに設定する。 |
| プッシュした変更が見えない | 接続先ブランチが違う | Apidogの接続ブランチと、確認しているGitブランチが一致しているか確認する。 |
| 同期状態が最新にならない | 未プッシュのローカル編集がある、またはプルが必要 | 保留中の編集をコミットしてプッシュする。Git側に変更がある場合は先にプルする。 |
| 仕様のマージ競合が発生する | 同じ行に対する複数の編集 | YAMLの競合を通常通り解決し、OpenAPIとして有効な状態にしてから再同期する。 |
| バックアップが実行されない | スケジュールされたオフピーク時間にまだ達していない | 次のバックアップサイクルを待つ。設定したリポジトリとブランチも確認する。 |
| 意図しない編集が残った | コミット前の実験的な変更 | 未プッシュの編集を破棄し、最後に同期された状態へ戻す。 |
認証問題が繰り返される場合は、最初にトークンの有効期限、スコープ、組織承認を確認してください。多くの「突然動かなくなった」問題は、トークン失効または組織側の承認不足で説明できます。
よくある質問
同期は一方向ですか、双方向ですか？
使う機能によります。
Spec-Firstモードは双方向です。Apidogで編集した仕様をGitへプッシュし、Git側の変更をApidogへプルできます。
自動Gitバックアップは一方向です。ApidogからGitへ仕様をエクスポートしますが、Git側の変更はApidogへ読み戻しません。
仕様はどこに保存されますか？
接続したGitリポジトリに保存されます。
Spec-Firstモードでは、OpenAPIドキュメントは接続したブランチにコミットされます。自動バックアップでは、各モジュールのOpenAPI/Swaggerファイルが設定したリポジトリへコミットされます。
どちらの場合も、Gitがバージョン管理されたコピーを保持します。
どのブランチに同期すべきですか？
正規の仕様にはmainを使い、作業中の変更には機能ブランチを使うのが一般的です。
機能ブランチに同期すれば、仕様変更もコード変更と同じようにプルリクエストでレビューできます。
トークンが失効した場合はどうなりますか？
ApidogがGitへ書き込めなくなるため、プッシュやバックアップが失敗します。
GitHubまたはGitLabでは再認証してください。Azure DevOpsや汎用Git接続では、新しいPATを発行してApidogに設定してください。
まとめ
Apidog Git連携には、2つの使い方があります。
- OpenAPI仕様をコードとして扱うなら、Spec-Firstモードで双方向同期する
- ワークフローを変えずに履歴と復旧手段を確保したいなら、自動Gitバックアップを使う
GitHub、GitLab、Azure DevOpsに接続できるため、既存のGit環境をそのまま活用できます。
実装時は、次の順序で進めると安全です。
- 利用する機能を決める：同期、バックアップ、または両方
- Gitプロバイダーを接続する
- リポジトリとブランチを選択する
- プッシュ権限を持つメンバーを限定する
- PATやOAuth権限を最小スコープにする
- 機能ブランチとPRレビューを使って仕様変更を管理する
- 競合が起きたら通常のGitマージ競合として解決する
仕様変更にレビューと履歴を持たせたいチームは、Spec-Firstモードを導入してください。まずは安全網を作りたい場合は、自動Gitバックアップから始めるのが簡単です。多くのチームでは、両方を組み合わせることで、API仕様をGit上で継続的に管理できます。
Top comments (0)