まとめ
SwaggerHubの同期競合は、同時編集やGit連携が競合する仕様バージョンを作成する際に発生します。解決策としては、競合するバージョンを特定し、手動で変更をマージして再コミットすることが含まれます。予防は解決よりも優れています。明確な所有権、ブランチの規律、およびロックの慣習により、ほとんどの競合は発生する前に削減されます。Apidogのブランチングモデルは、設計上、同時編集による競合を削減します。
はじめに
SwaggerHubの共同編集機能は本当に便利です。複数のチームメンバーが同じAPI定義で作業でき、変更はほぼリアルタイムで表示され、Git連携によりチームは仕様をソースリポジトリと同期させることができます。
しかし、共同作業は競合を引き起こします。2人のエンジニアが同時に同じエンドポイントを編集する。SwaggerHubで仕様が更新され、GitHubでも個別に更新され、同期プロセスが異なるバージョンに遭遇する。APIがレビュー中にドメインが更新される。これらの競合は管理可能ですが、予期せず発生し、チームに明確な解決プロセスがない場合、作業を妨げます。
このガイドでは、SwaggerHubで発生する競合の種類、各タイプの解決方法、およびより良いワークフロー規律によってそれらを防ぐ方法について説明します。最後のセクションでは、Apidogのアプローチが同種の問題をどのように処理するかについて説明します。
SwaggerHubにおける同期競合の種類
1. 同時編集競合。SwaggerHubでは、複数のユーザーが同時にAPI定義を編集できます。2人のユーザーが同時に仕様の同じセクションを編集すると、最後に保存した変更が優先されます。マージはなく、2番目の保存が最初のユーザーの変更を上書きします。これは技術的にはGitの意味での「競合」ではありませんが（エラー状態ではないため）、チームが注意しないとデータ損失を引き起こします。
2. SwaggerHubからGitへの同期競合。SwaggerHubはGitHub、GitLab、Bitbucketと統合されています。SwaggerHubで仕様が保存されると、設定されたリポジトリに自動プッシュできます。仕様ファイルがリポジトリに直接コミットされると、SwaggerHubに同期し直すことができます。どちらも独立して発生すると、SwaggerHubの同期プロセスが自動的に調整できない競合バージョンが発生します。
3. APIバージョンフォーク競合。SwaggerHubでAPIバージョンをフォークして新しい作業ブランチを作成し、変更をマージし直そうとすると、フォークとオリジナルの間の違いにより、手動での解決が必要な競合が発生する可能性があります。
4. ドメインバージョン不一致競合。APIが特定のバージョンのSwaggerHubドメインを参照しており、そのドメインバージョンが非推奨になったり、互換性のない変更が加えられたりした場合、参照しているAPIで解決エラーが発生する可能性があります。これは厳密には同期競合ではありませんが、同様の混乱を引き起こし、同様の解決手順が必要です。
5. 接続されたリポジトリでのGitプル競合。SwaggerHubに接続されたGitリポジトリに、仕様ファイルに競合を引き起こすブランチやマージがある場合、SwaggerHubの同期プロセスは次回同期するときにそれらの競合を表面化させます。
同時編集競合の解決
この種類の「競合」は最も一般的で、最も目に見えにくいものです。エラーメッセージはなく、あるユーザーの変更が単純に消えてしまいます。
解決策：
- 他のチームメンバーが保存した後に変更が失われていることに気づいた場合は、SwaggerHubの変更履歴（プランで利用可能な場合）を確認して、何が上書きされたかを確認します。
- 最後に保存したチームメンバーに、現在の仕様の状態をローカルコピーと比較するように依頼します。
- 失われた変更を手動で再入力します。
予防が唯一の真の解決策です。以下の予防策のセクションを参照してください。
SwaggerHubとGitの同期競合の解決
SwaggerHubとGitリポジトリが分岐した場合、通常、SwaggerHubのGit連携パネルに同期エラーが表示され、リモートにSwaggerHubのバージョンにはない変更があるため、自動プッシュできないことが示されます。
解決手順：
ステップ1：Gitリポジトリから現在の仕様をプルします。競合の原因となっているブランチからYAMLまたはJSONファイルをダウンロードします。
ステップ2：SwaggerHubから現在の仕様をプルします。SwaggerHubからAPIをYAMLとしてエクスポートします。
ステップ3：2つのファイルを差分比較します。任意の差分ツール（diff、VS Codeの差分ビュー、またはOpenAPI対応の差分ツール）を使用します。Gitに存在し、SwaggerHubには存在しない変更、およびその逆の変更を特定します。
ステップ4：手動でマージします。両方の変更セットを含む、調整された仕様バージョンを作成します。これには人間の判断が必要です。自動マージツールは、構文的には正しいが意味的に間違ったYAMLを生成する可能性があります。
ステップ5：単一の信頼できる情報源を選択します。SwaggerHubとGitのどちらが信頼できる情報源であるかを決定し、もう一方を更新します。Gitが信頼できる情報源である場合、マージされた仕様をリポジトリにコミットし、同期がそれをSwaggerHubにプルするようにします。SwaggerHubが信頼できる情報源である場合、マージされた仕様をSwaggerHubからGitにプッシュします。
ステップ6：同期を確認します。更新後、SwaggerHubのGit連携パネルに競合のないクリーンな同期状態が表示されていることを確認します。
便利なツール：openapi-diff。いくつかのOpenAPI差分ツールは、仕様のバージョンを、行ごとではなく、セマンティックレベル（エンドポイントの追加、フィールドの変更、破壊的変更と非破壊的変更）で比較します。oasdiffやopenapi-diffのようなツールは、生のYAML差分よりも明確な出力をもたらします。
ドメインバージョン不一致競合の解決
APIが、変更または非推奨になったドメインバージョンを参照している場合：
ステップ1：APIが参照しているドメインバージョンを特定します。仕様内の$ref URLを確認してください。それらにはバージョン番号が含まれています。
ステップ2：ドメインバージョンの変更履歴を確認します。現在固定されているバージョンと最新バージョンとの間で何が変更されたかを確認します。
ステップ3：変更が破壊的かどうかを評価します。新しいオプションフィールドの追加は非破壊的です。フィールドの削除、型の変更、プロパティ名の変更は破壊的変更です。
ステップ4：移行を決定した場合は、APIの$refパスを更新して新しいドメインバージョンを参照するようにします。更新後も仕様が正しく検証されることをテストします。
ステップ5：チームに更新を通知します。ドメインの変更が複数のAPIに影響する場合、すべてのチームが同じタイムラインで更新するように移行を調整します。
APIバージョンフォーク競合の解決
フォークされたAPIバージョンをメインバージョンにマージする場合：
ステップ1：フォークとメインバージョンの両方をYAMLファイルとしてエクスポートします。
ステップ2：OpenAPI差分ツールを使用して2つの仕様を差分比較します。
ステップ3：SwaggerHubエディターで、フォークからの変更をメインバージョンに手動で適用します（または、意図する最終状態に応じてその逆を行います）。
ステップ4：SwaggerHubのエディターでマージされた仕様を検証し、検証エラーがないことを確認します。
ステップ5：不要になったフォークを削除またはアーカイブします。
予防：競合の発生前に削減する
明確な所有権ゾーンを確立します。大規模なAPI仕様の異なるセクションを異なるチームメンバーに割り当てます。ある人は認証エンドポイントを所有し、別の人はリソースエンドポイントを所有します。編集ゾーンが重複する箇所で同時競合が発生します。
些細でない変更にはフォークを使用します。1時間以上かかる、またはレビューが必要な変更については、編集前にAPIバージョンをフォークします。これにより、マージの準備が整うまで、作業がメインバージョンから隔離されます。
Git同期プロトコルを確立します。Git連携を使用する場合は、どちらの方向が信頼できる情報源であるかを決定し、文書化します。「SwaggerHubがエディターであり、Gitが記録である」または「Gitが信頼できる情報源であり、SwaggerHubはそこから同期する」というように、両方が同時に独立した編集を行うわけではありません。
共有エリアを編集する前にコミュニケーションを取ります。Slack、チケットシステム、またはSwaggerHub自身のコメント機能を使用して、他の人が触れる可能性のあるセクションを編集しようとしているときに合図を送ります。非同期コミュニケーションは、ほとんどの同時編集による上書きを防ぎます。
ドメイン参照を明示的に固定します。$refパスでは、常に特定のドメインバージョンを参照し、浮動的な「最新」参照を使用しないでください。これにより、意図的な操作なしに破壊的変更がAPIに自動的に流入するのを防ぎます。
自動プッシュ設定を慎重に行います。SwaggerHubの保存時の自動プッシュは便利ですが、チームメンバーがGitリポジトリに直接仕様変更をコミットしている場合、競合のリスクを生み出します。両方の場所で開発者が仕様変更を行っている場合は、自動プッシュを無効にしてください。
Apidogが同様の問題をどのように処理するか
Apidogのコラボレーションモデルは、Gitスタイルのブランチングを中心に構築されており、これらの競合パターンのほとんどを設計段階で防ぎます。
同時上書きなし。Apidogでは、チームメンバーは個別のブランチで作業します。新しいエンドポイントを作成するエンジニアはブランチを作成し、作業を行い、完了したらレビューリクエストを開きます。別の変更を行う別のエンジニアも、別のブランチで同様の作業を行います。変更は、レビューおよび承認されるまでメインブランチにマージされません。これにより、「最後に保存した変更が優先される」という上書きの問題が完全に排除されます。
組み込みのレビューゲート。レビューと承認のワークフローは、仕様変更がメインブランチや下流チームが使用するドキュメントに影響を与える前に、明示的な検証ステップを経ることを意味します。
マージ時の競合検出。2つのブランチが同じエンドポイントまたはスキーマを変更する場合、Apidogのマージプロセスは競合を明示的に表面化します。チームは両方の変更セットを明確に把握した上で解決します。
ローカルファーストのワークフロー。外部Gitリポジトリとの同期競合を懸念するチームにとって、Apidogのローカルワークフローは影響範囲を縮小します。変更はGitにコミットされる前にプラットフォームで検証されます。
よくある質問
SwaggerHubには、競合解決用の組み込みUIがありますか？SwaggerHubには、一部のGit GUIツールのようなグラフィカルなマージ競合解決インターフェースはありません。競合解決は手動です。両方のバージョンをダウンロードし、SwaggerHubの外で差分比較し、解決済みのバージョンをアップロードします。
競合解決中に使用するのに最適なOpenAPI差分ツールは何ですか？oasdiffは、OpenAPI仕様の構造化された差分を生成し、破壊的変更を非破壊的追加とは別にフラグ付けする、適切に保守されたコマンドラインツールです。これは、API仕様作業において、生のYAML差分よりも有用な出力をもたらします。
他の人が編集できないようにSwaggerHubでAPIをロックできますか？SwaggerHubには、組み込みのファイルロックメカニズムはありません。最も近い回避策は、SwaggerHubのロールシステムを使用して、変更中に一時的に編集権限を制限し、その後元に戻すことです。
競合するAPIのどのバージョンが正しいかをどうやって知ることができますか？SwaggerHubのアクティビティログ（プランに含まれている場合）を確認して、誰がいつどのような変更を行ったかを確認します。Gitを使用している場合、コミット履歴は信頼できる記録です。どちらも決定打とならない場合は、関係するチームメンバーに相談して意図を再構築します。
依存しているドメインが更新されたときにSwaggerHubは通知しますか？SwaggerHubは、その通知システムを通じてドメインの更新を通知できます。これを設定しているかどうかは、通知設定によります。ドメイン変更のアラートを設定するには、「組織設定」>「通知」を確認してください。
Apidogへの移行は、すべての同期競合を防ぎますか？ブランチングは競合の発生頻度を大幅に削減しますが、完全に排除するわけではありません。同じエンドポイントを両方が変更する2つのブランチは、マージ時に依然として調整が必要です。ブランチングが行うのは、そうした競合を黙示的な上書きではなく、目に見える形で明示的にすることです。
SwaggerHubにおける同期競合は、ほとんどの場合、製品の問題ではなくワークフローの問題です。明確な所有権、ブランチの規律、および定義されたGit同期プロトコルにより、ほとんどの問題は発生する前に防止されます。競合が発生した場合でも、両方のバージョンをエクスポートし、適切なツールで差分比較し、手動でマージし、検証し、同期を確認するという系統的なプロセスにより、確実に解決されます。Apidogのブランチングモデルは、並行作業を明示的にすることで競合の頻度を削減しますが、どのような共同編集ツールも、同じ根本的な規律から恩恵を受けます。