ApidogをGitHub, GitLabに連携する方法

API仕様がApidogに存在し、信頼できる情報源がGitにある場合、両者を一致させたいと考えるでしょう。Apidog Git連携はそのギャップを埋めます。GitHub、GitLab、またはAzure DevOpsリポジトリをプロジェクトに接続し、OpenAPI仕様をバージョン管理にプッシュし、リポジトリの変更をApidogにプルバックできます。これにより、クリーンな監査証跡、仕様変更に対するコードレビュー、そしてアプリ内で何が起こっても残るバックアップが得られます。

これは包括的なリファレンスです。Apidogがサポートするすべてのプロバイダー、製品がGitと連携する両方の方法、そしてあなたが直面する実践的な決定事項（どのリポジトリ、どのブランチ、誰がプッシュできるか、何か問題が発生した場合の対処法）を網羅しています。GitHubに特化した詳細な手順のみが必要な場合は、OpenAPI仕様をGitHubに同期する方法に関する専用ガイドをお読みください。ここでは、より広範な内容を扱います。

Apidog Git連携ができること

Apidogは2つの異なる方法でGitと連携します。これらは異なる問題を解決し、一方だけ、他方だけ、または両方を使用できます。これらを混同することが最も一般的な混乱の原因となるため、まずそれらを区別しましょう。

最初の機能は、Spec-Firstモードによる双方向同期です。ApidogのIDEスタイルのエディタ内でOpenAPIドキュメントをYAMLまたはJSONとして編集し、変更をコミットして、接続されたブランチにプッシュします。他の誰かがリポジトリで仕様を更新した場合、それらの変更をApidogにプルバックします。これは真の往復連携です。編集はGitに流れ出し、リポジトリの変更はApidogに戻ってきます。

2番目の機能は、API仕様の自動Gitバックアップです。ここでは、Apidogが各モジュールのOpenAPI/Swaggerファイルをエクスポートし、スケジュールに基づいてリポジトリにプッシュします。これは一方向で、手間がかかりません。一度設定すれば、システムはあなたが手を煩わせることなく、仕様のバージョン管理されたコピーをGitに保持します。これは編集ワークフローではなく、安全網です。

この記事の残りの部分では、この区別を覚えておいてください。「同期」というときは、双方向のSpec-Firstモードフローを意味します。「バックアップ」というときは、スケジュールされた一方向のエクスポートを意味します。

サポートされているGitプロバイダー

Apidogは、ほとんどのチームがすでに使用している3つのプロバイダーをサポートしています。GitHubとGitLabは、それぞれのネイティブ認証フローを通じて直接接続します。Azure DevOpsは、標準的なHTTPS認証に対応する任意のGitホストと連携できる汎用Git接続を通じて接続します。

汎用Git接続は、緊急時の解決策となります。お使いのホストがGitHubやGitLabという名前でなくても、トークン認証を伴う標準的なHTTPS経由のGitに対応していれば、通常は汎用接続で処理できます。Azure DevOpsが主要なケースですが、HTTPSクローンURLを公開する自己ホスト型セットアップも同様の方法でカバーされます。

Gitプロバイダーを接続する

接続ステップでは、Apidogがリポジトリを読み書きするために必要なアクセス権を付与します。メカニズムはプロバイダーごとに若干異なりますが、形は同じです。認証し、リポジトリを選び、ブランチを選びます。

GitHubの場合、GitHubのOAuth画面を通じて認証を行います。Apidogは、仕様を読み込み、コミットをプッシュできるようにリポジトリへのアクセスを要求します。リポジトリが組織に属している場合、GitHubはリクエストを組織管理者に転送し、管理者によるサードパーティアクセス承認が必要になることがあります。個人リポジトリは、あなた自身のGitHubアカウントですぐに認証されます。

GitLabの場合、フローはGitHubと同様です。GitLabのOAuth画面を通じてログインし、リポジトリへのアクセスを許可します。Apidogがネットワーク経由でインスタンスに到達できる限り、自己管理型GitLabも機能します。

Azure DevOpsの場合、汎用Git接続を使用します。OAuthハンドシェイクの代わりに、リポジトリのHTTPSクローンURLと個人アクセストークン（PAT）を提供します。Azure DevOpsでコードの読み書き権限を持つPATを作成し、それをApidogに貼り付けます。トークンはApidogがコミットをプッシュするための資格情報であるため、必要なリポジトリにのみスコープを限定してください。

時間を節約できる、いくつかの権限に関する注意事項：

• 組織リポジトリと個人リポジリ。組織リポジトリは、一度管理者による連携の承認が必要となることがよくあります。認証が成功したように見えてもApidogがリポジトリを認識できない場合、通常は管理者の承認が不足しています。
• トークンのスコープを厳密に設定する。Azure DevOpsや任意の汎用接続の場合、ターゲットプロジェクトのコードに対する読み書き権限のみをPATに付与してください。フルアカウントトークンは避けてください。
• プライベートリポジトリも問題ありません。Apidogはプライベートリポジトリと連携できます。アクセスは、あなたが提供する認証またはトークンから来るものであり、公開されているかどうかとは関係ありません。

プロバイダーが接続されたら、リポジトリと、通常はmainブランチからApidogプロジェクトを作成します。この組み合わせが、仕様をバージョン管理の特定の場所に紐付けます。より広範なプラクティスに不慣れな場合は、すべてを設定する前に採用すべき慣習を、GitによるOpenAPIバージョン管理に関するガイドで説明しています。

Spec-Firstモードによる双方向同期

Spec-Firstモードは、双方向同期が実行される場所です。Apidogを、他のコードと同様にGitにコミットする仕様エディタに変えます。完全なリファレンスはApidog公式ドキュメントで確認できます。ここでは、実際の往復連携の仕組みを説明します。

OpenAPIドキュメントをYAMLまたはJSONとして直接編集します。エディタはIDEスタイルで、シンタックスハイライト、ライブバリデーション、オートコンプリート機能を提供するため、不適切な$refや必須フィールドの欠落は、プッシュ後ではなく入力中にすぐに表示されます。編集すると、左側のサイドバーがドキュメントをアウトライン、パス、操作、スキーマに自動的に解析し、大量の仕様をスクロールすることなくナビゲートできます。

典型的な編集は次のようになります。例えば、エンドポイントを追加する場合です。

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はそれをローカル編集としてステージします。その後、メッセージを付けてコミットし、接続されたブランチにプッシュします。これは他のGitワークフローとまったく同じです。プッシュが完了すると、同期インジケータが「今すぐ同期されました」と表示され、Apidogとブランチが同じ内容を保持していることを確認できます。

プル方向も同様に重要です。チームメイトがリポジトリで仕様を編集してプッシュした場合、それらの変更をApidogにプルしてローカルコピーを最新の状態に保ちます。これが連携を真に双方向にする理由です。リポジトリは単なるバックアップターゲットではなく、対等な存在なのです。

保持したくない編集を行った場合、コミットする前に未プッシュの編集を破棄できます。これにより、作業コピーは最後に同期された状態に戻ります。これは、試行錯誤中に変更を保持する価値がないと判断した場合に便利です。

このコミットとプッシュのリズムは、GitネイティブAPIワークフローの核心です。仕様変更は、コードベースの他の部分と同じレビュー、履歴、ロールバックの仕組みを経ます。レビュアーはプルリクエストのYAML差分にコメントし、承認がマージを制御し、API設計の履歴はコード履歴のように読み取れます。

API仕様の自動Gitバックアップ

バックアップ機能は、Apidog Git連携の静かなもう一方の側面であり、セットアップ後はほとんど何もする必要がありません。モジュールをリポジトリに向けたら、残りはApidogが処理します。

仕組みはこうです。Apidogは、各モジュールのOpenAPI/SwaggerファイルをGitリポジトリにバックアップでき、GitHub、GitLab、Azure DevOpsはすべてサポートされています。バックアップ設定を保存すると、システムは自動的にモジュールのOpenAPI仕様ファイルを指定されたリポジトリにプッシュします。プッシュは夜間のランダムなオフピーク時間帯に行われ、これにより作業時間外に処理され、負荷が分散されます。

保存されるのは、そのモジュールのエクスポートされたOpenAPI/Swaggerドキュメント、つまり現在のAPIコントラクトのスナップショットです。各プッシュがコミットであるため、Gitにバージョン履歴が蓄積されます。先週のコントラクトと今日のコントラクトを比較したり、フィールドがいつ変更されたかを正確に確認したり、必要であればリポジトリから以前のバージョンを直接復元したりすることができます。

バックアップフローは設計上、一方向です。Apidogはリポジトリに書き込みますが、そこから変更を読み戻すことはありません。リポジトリの編集をApidogに反映させたい場合は、それはバックアップの仕事ではなく、Spec-Firstモードの仕事です。チームの日常的な作業方法を変更することなく、耐久性と履歴を目的とする場合にバックアップを使用してください。

ブランチとリポジトリ構造の選択

事前に下す構造的な決定は、後になって連携がどれほどスムーズに感じられるかを左右します。主な疑問点は2つです。どのブランチを使うか、そしていくつのリポジトリを使うかです。

ブランチの選択。ほとんどのチームは、正規の仕様にはmainに同期し、作業中の設計には機能ブランチを使用します。Apidogを機能ブランチに向けることで、仕様変更を独立して反復作業し、プルリクエストを開き、レビューが通過したらマージできます。これにより、API設計はコードと同じブランチモデルに従います。Apidogを直接mainに向けるのはシンプルですが、レビューゲートをスキップするため、小規模チームや低リスクの変更に限定してください。

リポジトリは1つか複数か。唯一の正解はありませんが、トレードオフは明確です。

• APIごとに1つのリポジトリを使用すると、各仕様の履歴がクリーンに保たれ、アクセス制御が限定されます。異なるチームが異なるAPIを所有している場合に自然にフィットします。
• すべての仕様をモノレポにすると、すべてが一元化され、API間の検索とレビューが簡素化されます。1つのプラットフォームチームがAPIサーフェスを所有している場合にうまく機能します。ディレクトリレイアウトを予測可能にし、モジュールごとに1つのフォルダを維持することで、バックアップと同期が競合しないようにしてください。

モノレポを運用している場合は、各モジュールに独自のパスを設定してください。これにより、自動バックアップが整然と保たれ、レビューで仕様の差分が読みやすくなります。

チームの権限とアクセス

Git連携は認証情報に関わるため、誰が何を行えるかについて慎重に検討する価値があります。権限は2つの場所に存在します。Apidog内とGitプロバイダー内です。

Apidog内では、プロジェクト設定時にチームの権限が構成されます。そこで、誰が接続されたリポジトリに同期してプッシュできるかを決定します。プッシュ権限は仕様の所有者に限定し、他の全員には読み取りを許可します。これにより、API設計を閲覧しているだけの貢献者による誤ったプッシュを防ぐことができます。

Gitプロバイダー内では、資格情報が重要です。GitHubおよびGitLabの場合、OAuth認証はそれを許可したユーザーのアクセス権を運びます。Azure DevOpsおよび汎用接続の場合、個人アクセストークンが資格情報であり、秘密として扱ってください。トークンを共有ドキュメントに貼り付けたりせず、ターゲットリポジトリにのみスコープを設定し、他の秘密情報をローテーションするのと同じ頻度でローテーションしてください。誰かがチームを離れた場合、そのトークンを失効させ、まだアクティブなアカウントで再認証してください。

原則はシンプルです。連携は、その背後にある最も弱いトークンと同じくらいしかロックダウンされません。スコープを狭く保ち、所有権を明確にしてください。

マージの競合とドリフトの処理

Apidogは実際のGit履歴をコミットするため、Gitの競合モデルと、それを解決するためのGitのツールを継承します。競合は、2人のユーザーが同期する前に仕様の同じ部分を変更した場合に発生します。

シナリオを想像してみてください。あなたがApidogでOrderスキーマを編集してプッシュしました。しかし、その前にチームメイトがリポジトリ側で同じスキーマを編集してプッシュしていました。調整しようとすると、両側が重複する行を変更したため、GitはYAMLで競合を検出します。これはApidogの問題ではなく、YAMLファイルに対する通常のGitマージ競合であり、通常の方法で解決します。

競合を避けるには、プッシュする前にプルしてください。自分の変更をコミットする前に最新のリポジトリ状態をApidogに取り込むことで、作業コピーを最新に保ち、2つの編集が衝突する可能性のある期間を短縮します。競合が発生した場合は、他のマージ競合を解決するのと同じ方法でYAML上で解決します。正しい行を選択し、ドキュメントを有効な状態に保ち、再同期してください。エディタのライブバリデーションがここで役立ちます。OpenAPI構造を破壊する不完全なマージは、プッシュ後ではなくすぐに表示されます。

Apidogとリポジトリが静かに乖離していく「ドリフト」は、同じ問題のゆっくりとしたバージョンです。「今すぐ同期されました」というインジケータは、早期警告です。同期済みと表示されない場合、何かがプッシュされていないか、プルされていない状態です。その兆候を、ギャップが広がる前に調整を促す合図として扱ってください。

トラブルシューティング

ほとんどの連携問題は、認証、ブランチ選択、または中断された同期に起因します。より深い問題があると仮定する前に、以下の表を確認してください。

認証が繰り返される問題である場合（通常そうですが）、まず資格情報が有効で正しくスコープ設定されていることを確認してください。トークンの失効や組織承認の欠落が、「突然動作しなくなった」という報告の大部分を説明しています。

よくある質問

同期は一方向ですか、双方向ですか？

使用している機能によります。Spec-Firstモードは双方向です。編集をGitにプッシュし、リポジトリの変更をApidogにプルバックします。自動バックアップは一方向です。Apidogは各モジュールの仕様をスケジュールに基づいてリポジトリにエクスポートし、変更を読み戻しません。

仕様はどこに保存されますか？

接続するGitリポジトリに保存されます。Spec-Firstモードでは、OpenAPIドキュメントはプッシュするブランチに存在します。自動バックアップの場合、各モジュールのエクスポートされたOpenAPI/Swaggerファイルは、設定したリポジトリにコミットされます。どちらの場合も、Gitがバージョン管理されたコピーを保持し、あなたはリポジトリを完全に制御できます。

どのブランチに同期すべきですか？

正規の仕様にはmainを使用し、作業中の変更には機能ブランチを使用してください。機能ブランチに同期することで、仕様変更をプルリクエストとレビューを経てマージすることができ、これはコードがGitを介して移動する方法を反映しています。

トークンが失効した場合、どうなりますか？

Apidogが書き込みアクセス権を持たなくなるため、プッシュが失敗し始めます。プロバイダーを再認証するか、Azure DevOpsおよび汎用接続の場合は、新しい個人アクセストークンを生成してApidogで更新してください。資格情報が復元されると、同期とバックアップは正常に再開されます。

結論

Apidog Git連携は、2つの補完的なツールを提供します。仕様をコードとして扱うチーム向けのSpec-Firstモードによる双方向同期と、バージョン管理された安全網を求めるすべての人向けのモジュールごとの自動バックアップです。どちらの機能もGitHub、GitLab、Azure DevOpsで動作するため、新しいプロバイダーを導入するのではなく、すでに使用しているプロバイダーに接続できます。

目標に合った機能を選択してください。すべての仕様変更に対してレビューと履歴を残したい場合は、Spec-Firstモードを設定し、コミットとプッシュのリズムを採用してください。ワークフローを変更せずに耐久性を確保したい場合は、バックアップをオンにし、夜間のプッシュに任せてください。多くのチームは両方を使用しています。連携の準備ができたら、プロバイダーを接続し、プロジェクトをリポジトリとブランチに向け、API仕様を他の作業が行われている場所と同じ場所に配置してください。