要約
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のブランチモデルは、並行作業を明示的にすることで競合の頻度を減らしますが、どのような共同編集ツールでも同じ基本的な規律が役立ちます。