요약 (TL;DR)
SwaggerHub 동기화 충돌은 동시 편집 또는 Git 통합으로 인해 사양 버전이 충돌할 때 발생합니다. 해결책은 충돌하는 버전을 식별하고, 수동으로 변경 사항을 병합하고, 다시 커밋하는 것입니다. 해결하는 것보다 예방이 더 중요합니다. 명확한 소유권, 브랜치 규율 및 잠금 규칙은 대부분의 충돌을 발생하기 전에 줄여줍니다. Apidog의 브랜칭 모델은 동시 편집 충돌을 애초에 줄이도록 설계되었습니다.
소개
SwaggerHub의 협업 편집 기능은 매우 유용합니다. 여러 팀원이 동일한 API 정의에서 작업할 수 있고, 변경 사항은 거의 실시간으로 표시되며, Git 통합을 통해 팀은 사양을 소스 저장소와 동기화할 수 있습니다.
하지만 협업은 충돌을 초래합니다. 두 명의 엔지니어가 동시에 동일한 엔드포인트를 편집합니다. SwaggerHub와 GitHub에서 사양이 별도로 업데이트되고, 동기화 프로세스가 분기된 버전과 충돌합니다. API가 검토 중인 동안 도메인이 업데이트됩니다. 이러한 충돌은 관리할 수 있지만, 예상치 못하게 발생하고 팀에 명확한 해결 프로세스가 없을 때 방해가 됩니다.
이 가이드는 SwaggerHub에서 발생하는 충돌 유형, 각 유형을 해결하는 방법, 그리고 더 나은 워크플로우 규율로 충돌을 예방하는 방법을 설명합니다. 마지막 섹션에서는 Apidog의 접근 방식이 동일한 종류의 문제를 어떻게 처리하는지 다룹니다.
SwaggerHub의 동기화 충돌 유형
1. 동시 편집 충돌. SwaggerHub는 여러 사용자가 동시에 API 정의를 편집할 수 있도록 허용합니다. 두 사용자가 동시에 사양의 동일한 섹션을 편집하면 마지막 저장이 승리합니다. 병합은 없으며, 두 번째 저장이 첫 번째 사용자의 변경 사항을 덮어씁니다. 이것은 기술적으로 Git의 의미에서 "충돌"은 아니지만 (오류 상태는 없음), 팀이 주의하지 않으면 데이터 손실을 초래합니다.
2. SwaggerHub-to-Git 동기화 충돌. SwaggerHub는 GitHub, GitLab 및 Bitbucket과 통합됩니다. SwaggerHub에서 사양이 저장되면 구성된 저장소로 자동 푸시될 수 있습니다. 사양 파일이 저장소에 직접 커밋되면 SwaggerHub로 다시 동기화될 수 있습니다. 둘 다 독립적으로 발생하면 SwaggerHub의 동기화 프로세스가 자동으로 조정할 수 없는 충돌 버전이 발생합니다.
3. API 버전 분기 충돌. SwaggerHub에서 API 버전을 분기하여 새 작업 브랜치를 생성한 다음 변경 사항을 다시 병합하려고 할 때, 분기된 버전과 원본 버전 간의 차이로 인해 수동 해결이 필요한 충돌이 발생할 수 있습니다.
4. 도메인 버전 불일치 충돌. API가 특정 버전의 SwaggerHub 도메인을 참조하고, 해당 도메인 버전이 더 이상 사용되지 않거나 호환되지 않게 수정된 경우, 참조하는 API는 해결 오류가 발생할 수 있습니다. 이는 그 자체로는 동기화 충돌이 아니지만, 유사한 혼란을 야기하고 유사한 해결 단계를 필요로 합니다.
5. 연결된 저장소의 Git 풀 충돌. SwaggerHub에 연결된 Git 저장소에 사양 파일에서 충돌을 유발하는 브랜치 또는 병합이 있는 경우, SwaggerHub 동기화 프로세스는 다음 동기화 시 해당 충돌을 표면화합니다.
동시 편집 충돌 해결
이러한 유형의 "충돌"은 가장 일반적이며 가장 눈에 띄지 않습니다. 오류 메시지는 없으며, 한 사용자의 변경 사항이 단순히 사라집니다.
해결:
- 다른 팀원이 저장한 후 변경 사항이 누락된 것을 발견하면, SwaggerHub의 변경 기록(요금제에서 사용 가능한 경우)을 확인하여 무엇이 덮어쓰여졌는지 확인합니다.
- 마지막으로 저장한 팀원에게 현재 사양 상태를 로컬 복사본과 비교하도록 요청합니다.
- 누락된 변경 사항을 수동으로 다시 입력합니다.
예방만이 유일한 실제 해결책입니다. 아래 예방 섹션을 참조하세요.
SwaggerHub-to-Git 동기화 충돌 해결
SwaggerHub와 Git 저장소가 분기되었을 때, 일반적으로 SwaggerHub의 Git 통합 패널에서 동기화 오류를 보게 될 것입니다. 이는 원격에 SwaggerHub 버전에 없는 변경 사항이 있기 때문에 자동 푸시할 수 없음을 나타냅니다.
해결 단계:
1단계: Git 저장소에서 현재 사양을 가져옵니다. 충돌을 일으키는 브랜치에서 YAML 또는 JSON 파일을 다운로드합니다.
2단계: SwaggerHub에서 현재 사양을 가져옵니다. SwaggerHub에서 API를 YAML로 내보냅니다.
3단계: 두 파일을 비교합니다. 모든 비교 도구(diff, VS Code의 diff 뷰 또는 OpenAPI 인식 diff 도구)를 사용합니다. Git에 존재하지만 SwaggerHub에는 없는 변경 사항과 그 반대의 경우를 식별합니다.
4단계: 수동으로 병합합니다. 두 가지 변경 사항을 모두 포함하는 조정된 사양 버전을 생성합니다. 이는 인간의 판단이 필요합니다. 자동 병합 도구는 구문적으로 유효하지만 의미적으로 잘못된 YAML을 생성할 수 있습니다.
5단계: 단일 신뢰 소스를 선택합니다. SwaggerHub 또는 Git 중 어느 것이 권위 있는 소스인지 결정한 다음, 다른 쪽을 업데이트합니다. Git이 권위 있는 경우, 병합된 사양을 저장소에 커밋하고 동기화가 SwaggerHub로 가져오도록 합니다. SwaggerHub가 권위 있는 경우, 병합된 사양을 SwaggerHub에서 Git으로 푸시합니다.
6단계: 동기화를 확인합니다. 업데이트 후, SwaggerHub의 Git 통합 패널에 충돌 없이 깨끗한 동기화 상태가 표시되는지 확인합니다.
유용한 도구: openapi-diff. 여러 OpenAPI diff 도구는 줄 단위가 아닌 의미론적 수준(엔드포인트 추가, 필드 변경, 파괴적 변경 vs. 비파괴적 변경)에서 사양 버전을 비교합니다. oasdiff 또는 openapi-diff와 같은 도구는 원시 YAML diff보다 명확한 출력을 제공합니다.
도메인 버전 불일치 충돌 해결
API가 변경되거나 더 이상 사용되지 않는 도메인 버전을 참조하는 경우:
1단계: API가 참조하는 도메인 버전을 식별합니다. 사양의 $ref URL을 확인하십시오. 여기에는 버전 번호가 포함되어 있습니다.
2단계: 도메인 버전의 변경 로그를 검토합니다. 현재 고정된 버전과 최신 버전 사이에 무엇이 변경되었는지 확인합니다.
3단계: 변경 사항이 파괴적인지 평가합니다. 새 선택 필드를 추가하는 것은 비파괴적입니다. 필드를 제거하거나, 유형을 변경하거나, 속성 이름을 바꾸는 것은 파괴적 변경입니다.
4단계: 마이그레이션하기로 결정하면 API의 $ref 경로를 업데이트하여 새 도메인 버전을 참조하도록 합니다. 업데이트 후 사양이 여전히 올바르게 유효성 검사를 통과하는지 테스트합니다.
5단계: 팀을 업데이트합니다. 도메인 변경이 여러 API에 영향을 미치는 경우, 모든 팀이 동일한 타임라인에서 업데이트하도록 마이그레이션을 조율합니다.
API 버전 포크 충돌 해결
포크된 API 버전을 기본 버전으로 다시 병합할 때:
1단계: 포크된 버전과 기본 버전 모두를 YAML 파일로 내보냅니다.
2단계: OpenAPI diff 도구를 사용하여 두 사양을 비교합니다.
3단계: SwaggerHub 편집기에서, 포크된 버전의 변경 사항을 수동으로 기본 버전에 적용합니다(또는 의도된 최종 상태에 따라 그 반대로).
4단계: SwaggerHub 편집기에서 병합된 사양의 유효성을 검사하여 유효성 검사 오류가 없는지 확인합니다.
5단계: 더 이상 필요하지 않은 경우 포크를 삭제하거나 보관합니다.
예방: 충돌 발생 전에 줄이기
명확한 소유권 영역을 설정합니다. 큰 API 사양의 다른 섹션을 다른 팀원에게 할당합니다. 한 사람은 인증 엔드포인트를 소유하고, 다른 사람은 리소스 엔드포인트를 소유합니다. 편집 영역이 겹치는 곳에서 동시 충돌이 발생합니다.
사소하지 않은 변경에는 포크를 사용합니다. 한 시간 이상 걸리거나 검토가 필요한 변경 사항의 경우, 편집하기 전에 API 버전을 포크합니다. 이렇게 하면 병합할 준비가 될 때까지 작업이 기본 버전과 분리됩니다.
Git-동기화 프로토콜을 수립합니다. Git 통합을 사용하는 경우, 어느 방향이 권위 있는지를 결정하고 문서화합니다. "SwaggerHub는 편집기이고 Git은 기록이다" 또는 "Git이 진리의 원천이고 SwaggerHub는 Git에서 동기화한다"와 같이, 양쪽에서 독립적인 편집과 동시에 작동하지 않도록 합니다.
공유 영역을 편집하기 전에 소통합니다. Slack, 티켓 시스템 또는 SwaggerHub 자체의 댓글 기능을 사용하여 다른 사람도 만져야 할 섹션을 편집하려는 시점을 알립니다. 비동기 통신은 대부분의 동시 편집 덮어쓰기를 방지합니다.
도메인 참조를 명시적으로 고정합니다. $ref 경로에서 부동하는 "최신" 참조가 아닌 특정 도메인 버전을 항상 참조합니다. 이는 의도적인 조치 없이 API로 자동 파괴적 변경이 유입되는 것을 방지합니다.
자동 푸시 설정을 신중하게 설정합니다. SwaggerHub의 저장 시 자동 푸시는 편리할 수 있지만, 팀원들이 Git 저장소에 직접 사양 변경 사항을 커밋하는 경우 충돌 위험을 초래합니다. 개발자가 두 곳에서 사양 변경을 하는 경우 자동 푸시를 비활성화합니다.
Apidog가 동일한 문제를 처리하는 방법
Apidog의 협업 모델은 Git 스타일의 브랜칭을 기반으로 구축되어, 대부분의 이러한 충돌 패턴을 설계상 방지합니다.
동시 덮어쓰기 없음. Apidog에서는 팀원들이 별도의 브랜치에서 작업합니다. 새로운 엔드포인트를 생성하는 엔지니어는 브랜치를 생성하고, 작업을 수행하며, 완료되면 검토 요청을 엽니다. 다른 변경 사항을 만드는 다른 엔지니어는 별도의 브랜치에서 동일한 작업을 수행합니다. 변경 사항은 검토 및 승인될 때까지 메인 브랜치로 병합되지 않습니다. 이는 "마지막 저장이 승리한다"는 덮어쓰기 문제를 완전히 제거합니다.
내장된 검토 게이트. 검토 및 승인 워크플로우는 사양 변경 사항이 다운스트림 팀이 사용하는 메인 브랜치 또는 문서에 영향을 미치기 전에 명시적인 검증 단계를 거친다는 것을 의미합니다.
병합 시 충돌 감지. 두 브랜치가 동일한 엔드포인트 또는 스키마를 수정할 때, Apidog의 병합 프로세스는 충돌을 명시적으로 표면화합니다. 팀은 두 가지 변경 사항을 명확하게 파악하여 해결합니다.
로컬 우선 워크플로우. 외부 Git 저장소와의 동기화 충돌에 대해 우려하는 팀을 위해 Apidog의 로컬 워크플로우는 폭발 반경을 줄입니다. 변경 사항은 Git에 커밋되기 전에 플랫폼에서 유효성 검사를 거칩니다.
자주 묻는 질문
SwaggerHub에 내장된 충돌 해결 UI가 있습니까? SwaggerHub는 일부 Git GUI 도구처럼 그래픽 병합 충돌 해결 인터페이스를 제공하지 않습니다. 충돌 해결은 수동으로 진행됩니다. 두 버전을 다운로드하고, SwaggerHub 외부에서 비교한 다음, 해결된 버전을 업로드해야 합니다.
충돌 해결 시 사용하기에 가장 좋은 OpenAPI diff 도구는 무엇입니까? oasdiff는 잘 관리되는 명령줄 도구로, OpenAPI 사양의 구조화된 diff를 생성하여 파괴적 변경 사항을 비파괴적 추가 사항과 별도로 표시합니다. API 사양 작업에는 원시 YAML diff보다 더 유용한 출력입니다.
SwaggerHub에서 다른 사람이 편집하지 못하도록 API를 잠글 수 있습니까? SwaggerHub에는 내장된 파일 잠금 메커니즘이 없습니다. 가장 가까운 해결책은 SwaggerHub의 역할 시스템을 사용하여 변경하는 동안 편집 권한을 일시적으로 제한한 다음 복원하는 것입니다.
충돌하는 API의 어떤 버전이 올바른지 어떻게 알 수 있습니까? SwaggerHub의 활동 로그(요금제에 포함된 경우)를 확인하여 누가 어떤 변경 사항을 언제 만들었는지 확인합니다. Git을 사용하는 경우, 커밋 기록은 신뢰할 수 있는 기록입니다. 둘 다 결정적이지 않은 경우, 관련 팀원들과 상의하여 의도를 재구성합니다.
의존하는 도메인이 업데이트되면 SwaggerHub에서 알려줍니까? SwaggerHub는 알림 시스템을 통해 도메인 업데이트를 알릴 수 있습니다. 이 기능을 구성했는지 여부는 알림 설정에 따라 다릅니다. 조직 설정 > 알림에서 도메인 변경에 대한 알림을 구성하십시오.
Apidog로 마이그레이션하면 모든 동기화 충돌이 방지됩니까? 브랜칭은 충돌 빈도를 크게 줄이지만, 완전히 제거하지는 않습니다. 동일한 엔드포인트를 모두 수정하는 두 브랜치는 병합할 때 여전히 조정해야 합니다. 브랜칭은 그러한 충돌을 침묵하는 덮어쓰기가 아닌 명확하게 보이도록 만듭니다.
SwaggerHub의 동기화 충돌은 대부분 제품 문제가 아닌 워크플로우 문제입니다. 명확한 소유권, 브랜치 규율 및 정의된 Git-동기화 프로토콜은 대부분의 문제를 발생하기 전에 방지합니다. 충돌이 발생하면, 체계적인 프로세스(두 버전 내보내기, 적절한 도구로 비교, 수동 병합, 유효성 검사 및 동기화 확인)가 안정적으로 해결합니다. Apidog의 브랜칭 모델은 병렬 작업을 명시적으로 만들어 충돌 빈도를 줄이지만, 모든 협업 편집 도구는 동일한 기본 규율의 혜택을 받습니다.