요약 (TL;DR)
SwaggerHub 동기화 충돌은 동시 편집 또는 Git 통합으로 인해 사양 버전이 충돌할 때 발생합니다. 해결책은 충돌하는 버전을 식별하고, 변경 사항을 수동으로 병합하고, 다시 커밋하는 것입니다. 예방이 해결보다 낫습니다. 명확한 소유권, 브랜치 규율 및 잠금 규칙은 대부분의 충돌이 발생하기 전에 줄여줍니다. Apidog의 브랜칭 모델은 동시 편집 충돌을 애초에 줄여줍니다.
서론
SwaggerHub의 공동 편집 기능은 정말 유용합니다. 여러 팀 구성원이 동일한 API 정의에서 작업할 수 있으며, 변경 사항은 거의 실시간으로 확인 가능하고, Git 통합을 통해 팀은 사양을 소스 저장소와 동기화 상태로 유지할 수 있습니다.
하지만 협업은 충돌을 야기합니다. 두 명의 엔지니어가 동시에 동일한 엔드포인트를 편집합니다. 사양이 SwaggerHub와 GitHub에서 각각 업데이트되고, 동기화 프로세스가 서로 다른 버전과 충돌합니다. API 검토 중에 도메인이 업데이트됩니다. 이러한 충돌은 관리 가능하지만, 예상치 못하게 발생하고 팀에 명확한 해결 프로세스가 없을 때 작업을 방해합니다.
이 가이드는 SwaggerHub에서 발생하는 충돌 유형, 각 유형을 해결하는 방법, 그리고 더 나은 워크플로 규율로 충돌을 예방하는 방법을 설명합니다. 마지막 섹션에서는 Apidog의 접근 방식이 동일한 종류의 문제를 어떻게 처리하는지 다룹니다.
SwaggerHub의 동기화 충돌 유형
1. 동시 편집 충돌.SwaggerHub는 여러 사용자가 동시에 API 정의를 편집할 수 있도록 합니다. 두 사용자가 동시에 사양의 동일한 섹션을 편집할 경우, 마지막 저장본이 우선합니다. 병합이 없으므로 두 번째 저장이 첫 번째 사용자의 변경 사항을 덮어씁니다. 이는 기술적으로 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단계: 두 파일을 비교하십시오. 모든 diff 도구(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가 거기에서 동기화합니다"와 같이 한쪽에서 독립적인 편집을 동시에 하지 마십시오.
공유 영역을 편집하기 전에 소통하십시오. Slack, 티켓 시스템 또는 SwaggerHub 자체의 댓글 기능을 사용하여 다른 사람도 건드려야 할 섹션을 편집하기 직전에 알리십시오. 비동기식 커뮤니케이션은 대부분의 동시 편집 덮어쓰기를 방지합니다.
도메인 참조를 명시적으로 고정하십시오. $ref 경로에서 항상 특정 도메인 버전을 참조하고, 유동적인 "최신" 참조를 사용하지 마십시오. 이는 의도적인 조치 없이 자동 주요 변경 사항이 API로 유입되는 것을 방지합니다.
자동 푸시 설정을 신중하게 구성하십시오. SwaggerHub의 저장 시 자동 푸시는 편리할 수 있지만, 팀 구성원이 Git 저장소에 사양 변경 사항을 직접 커밋하는 경우 충돌 위험을 야기합니다. 개발자가 두 곳에서 사양 변경을 하는 경우 자동 푸시를 비활성화하십시오.
Apidog는 동일한 문제를 어떻게 처리하는가
Apidog의 협업 모델은 Git 스타일 브랜칭을 중심으로 구축되어 있으며, 이는 대부분의 이러한 충돌 패턴을 애초에 방지합니다.
동시 덮어쓰기 없음. Apidog에서는 팀 구성원들이 개별 브랜치에서 작업합니다. 새로운 엔드포인트를 생성하는 엔지니어는 브랜치를 생성하고, 작업을 수행한 다음, 완료되면 검토 요청을 엽니다. 다른 변경 사항을 만드는 다른 엔지니어는 별도의 브랜치에서 동일하게 작업합니다. 변경 사항은 검토되고 승인될 때까지 주 브랜치에 병합되지 않습니다. 이는 "마지막 저장본이 우선하는" 덮어쓰기 문제를 완전히 제거합니다.
내장된 검토 게이트. 검토 및 승인 워크플로는 사양 변경 사항이 주 브랜치나 다운스트림 팀이 사용하는 문서에 영향을 미치기 전에 명시적인 검증 단계를 거친다는 것을 의미합니다.
병합 시 충돌 감지. 두 브랜치가 동일한 엔드포인트 또는 스키마를 수정할 때, Apidog의 병합 프로세스는 충돌을 명시적으로 드러냅니다. 팀은 양쪽 변경 사항을 명확하게 파악하여 이를 해결합니다.
로컬 우선 워크플로. 외부 Git 저장소와의 동기화 충돌을 우려하는 팀의 경우, Apidog의 로컬 워크플로는 영향 범위를 줄여줍니다. 변경 사항은 Git에 커밋되기 전에 플랫폼에서 유효성 검사를 거칩니다.
자주 묻는 질문 (FAQ)
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의 브랜칭 모델은 병렬 작업을 명확하게 하여 충돌 빈도를 줄여주지만, 모든 공동 편집 도구는 동일한 기본 규율의 이점을 얻습니다.