API 사양이 Apidog에 있지만 진실의 근원이 Git에 있다면, 이 둘이 일치하기를 원할 것입니다. Apidog Git 통합은 이러한 간극을 메워줍니다. 프로젝트에 GitHub, GitLab 또는 Azure DevOps 저장소를 연결하여 OpenAPI 사양을 버전 제어 시스템으로 푸시하고, 저장소 변경 사항을 다시 Apidog로 가져올 수 있습니다. 이를 통해 깔끔한 감사 추적, 사양 변경에 대한 코드 검토, 그리고 앱 내에서 발생하는 모든 상황에서 살아남는 백업을 얻을 수 있습니다.
이 문서는 포괄적인 참조 자료입니다. Apidog가 지원하는 모든 공급자, 제품이 Git과 통신하는 두 가지 방식, 그리고 직면하게 될 실제적인 결정 사항들(어떤 저장소, 어떤 브랜치, 누가 푸시할 수 있는지, 문제가 발생했을 때 어떻게 해야 하는지)을 다룹니다. GitHub에 대한 집중적인 안내만 필요한 경우, OpenAPI 사양을 GitHub와 동기화하는 방법에 대한 전용 가이드를 참조하십시오. 여기서는 더 광범위하게 다룰 것입니다.
Apidog Git 통합의 기능
Apidog는 Git과 두 가지 뚜렷한 방식으로 통신합니다. 이들은 서로 다른 문제를 해결하며, 하나만 사용하거나 둘 다 사용할 수 있습니다. 이들을 혼동하는 것이 가장 흔한 혼란의 원인이므로, 먼저 이들을 구분해 봅시다.
첫 번째 기능은 Spec-First 모드를 통한 양방향 동기화입니다. Apidog의 IDE 스타일 편집기 내에서 OpenAPI 문서를 YAML 또는 JSON으로 편집하고, 변경 사항을 커밋한 다음 연결된 브랜치로 푸시합니다. 다른 사람이 저장소에서 사양을 업데이트하면, 해당 변경 사항을 Apidog로 다시 가져옵니다. 이것은 진정한 왕복입니다: 편집 내용은 Git으로 나가고, 저장소 변경 사항은 다시 들어옵니다.
두 번째 기능은 API 사양의 자동 Git 백업입니다. 이 경우, Apidog는 각 모듈의 OpenAPI/Swagger 파일을 내보내고 이를 일정에 따라 저장소로 푸시합니다. 이것은 단방향이며 수동 개입이 필요 없습니다. 한 번만 구성하면, 시스템이 사용자의 개입 없이 Git에 사양의 버전 관리된 사본을 유지합니다. 이것은 편집 워크플로우가 아니라 안전망입니다.
| 기능 | 방향 | 트리거 | 가장 적합한 경우 |
|---|---|---|---|
| Spec-First 모드 동기화 | 양방향 (푸시 및 풀) | 수동 커밋/푸시, 수동 풀 | 사양을 코드로 취급하고 모든 변경 사항에 대한 검토를 원하는 팀 |
| 자동 Git 백업 | 단방향 (Apidog → Git) | 예약, 비피크 시간 | 작업 방식을 변경하지 않고 버전 관리된 백업을 원하는 모든 사람 |
이 문서의 나머지 부분을 읽을 때 이 구분을 염두에 두십시오. "동기화"라고 말할 때, 우리는 양방향 Spec-First 모드 흐름을 의미합니다. "백업"이라고 말할 때, 우리는 예약된 단방향 내보내기를 의미합니다.
지원되는 Git 공급자
Apidog는 대부분의 팀이 이미 사용하는 세 가지 공급자를 지원합니다. GitHub와 GitLab은 기본 인증 흐름을 통해 직접 연결됩니다. Azure DevOps는 표준 HTTPS 인증을 지원하는 모든 Git 호스트와 작동하는 일반 Git 연결을 통해 연결됩니다.
| 공급자 | 인증 방식 | 참고 |
|---|---|---|
| GitHub | OAuth 인증 (GitHub 로그인) | 개인 및 조직 저장소에서 작동합니다. 조직 저장소는 관리자의 연결 승인이 필요할 수 있습니다. |
| GitLab | OAuth 인증 (GitLab 로그인) | gitlab.com 및 Apidog에서 접근 가능한 자체 관리 인스턴스를 지원합니다. |
| Azure DevOps | 일반 Git 연결 (HTTPS + 토큰) | 저장소의 HTTPS URL과 저장소 범위가 있는 개인 액세스 토큰을 통해 연결합니다. |
일반 Git 연결은 비상 탈출구입니다. 호스트가 GitHub 또는 GitLab이 아니더라도, 토큰 인증을 사용하는 표준 Git over HTTPS를 지원한다면, 일반 연결로 처리할 수 있습니다. Azure DevOps가 대표적인 경우이지만, HTTPS 복제 URL을 노출하는 자체 호스팅 설정도 동일한 방식으로 커버됩니다.
Git 공급자 연결
연결 단계는 Apidog가 저장소를 읽고 쓰는 데 필요한 액세스 권한을 부여하는 곳입니다. 메커니즘은 공급자마다 약간 다르지만, 형태는 동일합니다: 권한 부여, 저장소 선택, 브랜치 선택.
GitHub의 경우, GitHub의 OAuth 화면을 통해 권한을 부여합니다. Apidog는 사양을 읽고 커밋을 푸시할 수 있도록 저장소 액세스를 요청합니다. 저장소가 조직에 속해 있다면, GitHub는 제3자 액세스를 승인하는 조직 관리자를 통해 요청을 라우팅할 수 있습니다. 개인 저장소는 사용자 계정으로 즉시 권한을 부여합니다.
GitLab의 경우, 흐름은 GitHub와 유사합니다. GitLab의 OAuth 화면을 통해 로그인하고 저장소 액세스를 부여합니다. 자체 관리 GitLab은 Apidog가 네트워크를 통해 인스턴스에 도달할 수 있는 한 작동합니다.
Azure DevOps의 경우, 일반 Git 연결을 사용합니다. OAuth 핸드셰이크 대신, 저장소의 HTTPS 클론 URL과 개인 액세스 토큰(PAT)을 제공합니다. Azure DevOps에서 코드를 읽고 쓸 수 있는 권한으로 PAT를 생성한 다음, 이를 Apidog에 붙여넣습니다. 이 토큰은 Apidog가 커밋을 푸시할 수 있도록 하는 자격 증명이므로, 필요한 저장소에만 범위를 지정하십시오.
시간을 절약해 줄 몇 가지 권한 관련 참고 사항:
- 조직 vs 개인 저장소. 조직 저장소는 종종 관리자가 통합을 한 번 승인해야 합니다. 권한 부여가 성공한 것 같지만 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와 브랜치가 동일한 내용을 가지고 있음을 확인시켜 줍니다.
풀(pull) 방향도 마찬가지로 중요합니다. 팀원이 저장소에서 사양을 편집하고 푸시하면, 해당 변경 사항을 Apidog로 가져와 로컬 사본을 최신 상태로 만듭니다. 이것이 통합을 진정으로 양방향으로 만드는 것입니다: 저장소는 단순한 백업 대상이 아니라 동등한 존재입니다.
유지하고 싶지 않은 편집을 했다면, 커밋하기 전에 푸시되지 않은 편집을 버릴 수 있습니다. 이렇게 하면 작업 복사본이 마지막으로 동기화된 상태와 일치하도록 되돌려지며, 이는 실험 중이고 변경 사항을 유지할 가치가 없다고 결정했을 때 유용합니다.
이러한 커밋-앤-푸시 리듬은 Git 네이티브 API 워크플로우의 핵심입니다. 사양 변경 사항은 코드베이스의 나머지 부분과 동일한 검토, 기록 및 롤백 메커니즘을 거칩니다. 검토자들은 풀 리퀘스트의 YAML 차이점에 대해 코멘트하고, 승인은 병합을 제어하며, API 디자인 기록은 코드 기록과 유사하게 읽힙니다.
API 사양의 자동 Git 백업
백업 기능은 Apidog Git 통합의 더 조용한 절반이며, 설정 후에는 사용자에게 거의 아무것도 요구하지 않습니다. 모듈을 저장소에 연결하면, Apidog가 나머지를 처리합니다.
메커니즘은 다음과 같습니다. Apidog는 각 모듈의 OpenAPI/Swagger 파일을 Git 저장소에 백업할 수 있으며, GitHub, GitLab, Azure DevOps 모두 지원됩니다. 백업 구성을 저장하면, 시스템은 자동으로 모듈의 OpenAPI Spec 파일을 지정된 저장소로 푸시합니다. 푸시는 야간의 무작위 비피크 시간대에 발생하여 사용자의 업무 시간을 방해하지 않고 부하를 분산시킵니다.
저장되는 것은 해당 모듈에 대한 내보낸 OpenAPI/Swagger 문서, 즉 현재 API 계약의 스냅샷입니다. 각 푸시가 커밋이므로, Git에 버전 기록이 축적됩니다. 지난주의 계약과 오늘의 계약을 비교하고, 필드가 언제 변경되었는지 정확히 확인하며, 필요한 경우 저장소에서 이전 버전을 직접 복원할 수 있습니다.
백업 흐름은 설계상 단방향입니다. Apidog는 저장소에 쓰기만 하고, 변경 사항을 다시 읽어오지는 않습니다. 저장소 편집 내용이 Apidog로 흘러들어오기를 원한다면, 그것은 백업이 아닌 Spec-First 모드의 역할입니다. 팀의 일상적인 작업 방식을 변경하지 않고 영속성과 기록을 목표로 할 때 백업을 사용하십시오.
브랜치 및 저장소 구조 선택
사전에 내리는 구조적 결정은 나중에 통합이 얼마나 원활하게 느껴질지 형성합니다. 두 가지 질문이 중요합니다: 어떤 브랜치, 그리고 몇 개의 저장소.
브랜치 선택. 대부분의 팀은 표준 사양을 위해 main 브랜치에 동기화하고, 진행 중인 설계를 위해 별도의 브랜치를 사용합니다. Apidog를 별도의 브랜치로 지정하면 사양 변경 사항을 독립적으로 반복하고, 풀 리퀘스트를 열고, 검토가 통과되면 병합할 수 있습니다. 이렇게 하면 API 디자인이 코드와 동일한 브랜치 모델을 따르게 됩니다. Apidog를 main 브랜치로 직접 지정하는 것이 더 간단하지만 검토 단계를 건너뛰므로, 소규모 팀이나 위험이 낮은 변경 사항에 대해 남겨두십시오.
하나의 저장소 또는 여러 개. 정답은 없지만, 장단점은 명확합니다:
- API당 하나의 저장소는 각 사양의 기록을 깨끗하게 유지하고 액세스 제어를 좁게 만듭니다. 서로 다른 팀이 서로 다른 API를 소유할 때 자연스럽게 적합합니다.
- 모든 사양을 위한 모노레포는 모든 것을 중앙 집중화하고 API 간 검색 및 검토를 단순화합니다. 하나의 플랫폼 팀이 API 표면을 소유할 때 잘 작동합니다. 백업과 동기화가 충돌하지 않도록 디렉토리 레이아웃을 예측 가능하게 유지하고, 모듈당 하나의 폴더를 사용하십시오.
모노레포를 운영하는 경우, 각 모듈에 고유한 경로를 부여하십시오. 이렇게 하면 자동 백업이 깔끔하게 유지되고 검토 시 사양 차이점을 쉽게 읽을 수 있습니다.
팀 권한 및 액세스
Git 통합은 자격 증명과 관련이 있으므로, 누가 무엇을 할 수 있는지 신중하게 결정하는 것이 중요합니다. 권한은 두 곳에 있습니다: Apidog 내부와 Git 공급자 내부.
Apidog 내부에서 팀 권한은 프로젝트 설정 중에 구성됩니다. 여기서 연결된 저장소에 동기화하고 푸시할 수 있는 사람을 결정합니다. 푸시 권한을 사양 소유자에게만 제한하고, 다른 모든 사람은 읽기만 허용하십시오. 이는 API 디자인을 탐색하는 기여자들의 실수로 인한 푸시를 방지합니다.
Git 공급자 내부에서는 자격 증명이 중요합니다. GitHub 및 GitLab의 경우, OAuth 인증은 권한을 부여한 사용자의 액세스 권한을 가집니다. Azure DevOps 및 일반 연결의 경우, 개인 액세스 토큰이 자격 증명이므로 비밀처럼 취급하십시오. 토큰을 공유 문서에 붙여넣지 말고, 대상 저장소에만 범위를 지정하고, 다른 비밀을 교체하는 것과 동일한 주기로 교체하십시오. 팀을 떠나는 사람이 있다면, 해당 토큰을 취소하고 활성 상태인 계정으로 다시 권한을 부여하십시오.
원칙은 간단합니다: 통합은 그 뒤에 있는 가장 약한 토큰만큼만 잠겨 있습니다. 범위를 좁게 유지하고 소유권을 명확히 하십시오.
병합 충돌 및 드리프트 처리
Apidog는 실제 Git 기록을 커밋하므로, Git의 충돌 모델과 이를 해결하는 Git 도구를 계승합니다. 충돌은 두 사람이 동기화하기 전에 사양의 동일한 부분을 변경할 때 발생합니다.
시나리오를 상상해 보세요. 당신이 Apidog에서 Order 스키마를 편집하고 푸시합니다. 한 팀원이 저장소에서 동일한 스키마를 편집하고 먼저 푸시했습니다. 조정하려고 할 때, Git은 YAML에서 충돌을 표시합니다. 양쪽에서 겹치는 줄을 변경했기 때문입니다. 이것은 Apidog 문제가 아닙니다. YAML 파일에서 발생하는 일반적인 Git 병합 충돌이며, 일반적인 방식으로 해결합니다.
충돌을 피하려면 푸시하기 전에 풀(pull)하십시오. 자신의 변경 사항을 커밋하기 전에 최신 저장소 상태를 Apidog로 가져오면 작업 복사본이 최신 상태로 유지되고 두 편집이 충돌할 수 있는 시간을 줄일 수 있습니다. 충돌이 발생하면, 다른 병합 충돌을 해결하는 것과 동일한 방식으로 YAML에서 해결하십시오: 올바른 줄을 선택하고, 문서를 유효하게 유지한 다음, 다시 동기화하십시오. 편집기의 실시간 유효성 검사가 여기서 도움이 됩니다. OpenAPI 구조를 손상시키는 잘못된 병합은 푸시 후에 나타나는 것이 아니라 즉시 표시됩니다.
Apidog와 저장소가 조용히 달라지는 '드리프트'는 동일한 문제의 느린 버전입니다. "방금 동기화됨" 표시기는 초기 경고입니다. 동기화됨으로 표시되지 않으면, 푸시되지 않았거나 풀되지 않은 무언가가 있는 것입니다. 이는 간극이 벌어지기 전에 조정해야 할 신호로 간주하십시오.
문제 해결
대부분의 통합 문제는 인증, 브랜치 선택 또는 중단된 동기화로 거슬러 올라갑니다. 더 깊은 문제가 있다고 가정하기 전에 표를 통해 확인하십시오.
| 증상 | 가능성 있는 원인 | 해결책 |
|---|---|---|
| 권한 부여 실패 또는 저장소가 나타나지 않음 | 조직이 타사 액세스를 승인하지 않았거나, 토큰에 범위가 부족함 | 조직 관리자가 GitHub/GitLab 앱을 승인하도록 하십시오; Azure DevOps의 경우, 읽기/쓰기 코드 범위로 PAT를 재발급하십시오 |
| 푸시 거부됨 | 토큰이 취소되었거나 만료되었거나, 쓰기 권한이 없음 | 공급자를 다시 인증하십시오; 일반 연결의 경우, 새로운 PAT를 생성하고 Apidog에서 업데이트하십시오 |
| 변경 사항이 푸시되었으나 보이지 않음 | 잘못된 브랜치를 가리킴 | 연결된 브랜치가 커밋을 예상하는 위치와 일치하는지 확인하십시오; 프로젝트 설정에서 브랜치를 전환하십시오 |
| 동기화 멈춤 또는 "방금 동기화됨"이 나타나지 않음 | 푸시되지 않은 로컬 편집이 있거나, 풀(pull)이 필요함 | 보류 중인 편집을 커밋하고 푸시하십시오; 팀원이 푸시했다면, 먼저 풀(pull)한 다음 다시 동기화하십시오 |
| 사양에 병합 충돌 발생 | 동일한 줄에 대한 두 가지 편집 | YAML 충돌을 정상적으로 해결하고, 문서를 유효하게 유지한 다음, 다시 동기화하십시오 |
| 백업이 실행되지 않음 | 예약된 푸시가 아직 비피크 시간대에 도달하지 않음 | 백업은 야간의 무작위 시간대에 푸시됩니다; 다음 주기를 기다리거나 백업 저장소/브랜치 구성을 확인하십시오 |
| 유지할 의도가 없었던 편집 | 커밋 전의 실험적인 변경 사항 | "푸시되지 않은 편집 버리기"를 사용하여 마지막 동기화된 상태로 되돌리십시오 |
인증이 반복되는 문제(대부분 그렇습니다)라면, 자격 증명이 활성 상태이며 올바르게 범위가 지정되었는지 확인하는 것부터 시작하십시오. 취소된 토큰이나 누락된 조직 승인은 "작동이 중지되었다"는 보고의 대부분을 설명합니다.
자주 묻는 질문 (FAQ)
동기화는 단방향인가요, 양방향인가요?
어떤 기능을 사용하는지에 따라 다릅니다. Spec-First 모드는 양방향입니다: Git으로 편집 내용을 푸시하고 저장소 변경 사항을 다시 Apidog로 가져옵니다. 자동 백업은 단방향입니다: Apidog는 각 모듈의 사양을 일정에 따라 저장소로 내보내고 변경 사항을 다시 읽어오지는 않습니다.
내 사양은 어디에 저장되나요?
연결하는 Git 저장소에 저장됩니다. Spec-First 모드의 경우, OpenAPI 문서는 푸시하는 브랜치에 있습니다. 자동 백업의 경우, 각 모듈의 내보낸 OpenAPI/Swagger 파일은 구성한 저장소에 커밋됩니다. 두 경우 모두 Git이 버전 관리된 사본을 보관하며, 당신은 저장소를 완전히 제어합니다.
어떤 브랜치로 동기화해야 하나요?
표준 사양을 위해 main 브랜치를 사용하고, 진행 중인 변경 사항을 위해 별도의 브랜치를 사용하십시오. 별도의 브랜치로 동기화하면 사양 변경 사항이 병합되기 전에 풀 리퀘스트 및 검토를 거칠 수 있으며, 이는 코드가 Git을 통해 이동하는 방식과 유사합니다.
토큰이 취소되면 어떻게 되나요?
Apidog가 더 이상 쓰기 액세스 권한을 가지지 않으므로 푸시가 실패하기 시작합니다. 공급자를 다시 인증하거나, Azure DevOps 및 일반 연결의 경우, 새로운 개인 액세스 토큰을 생성하여 Apidog에서 업데이트하십시오. 자격 증명이 복원되면 동기화 및 백업이 정상적으로 재개됩니다.
결론
Apidog Git 통합은 두 가지 보완적인 도구를 제공합니다: 사양을 코드로 취급하는 팀을 위한 Spec-First 모드를 통한 양방향 동기화와, 버전 관리된 안전망을 원하는 모든 사람을 위한 모듈별 자동 백업입니다. 두 기능 모두 GitHub, GitLab, Azure DevOps에서 작동하므로, 새로운 공급자를 채택하는 대신 이미 사용 중인 공급자를 연결할 수 있습니다.
목표에 맞는 기능을 선택하십시오. 모든 사양 변경 사항에 대한 검토와 기록을 원한다면 Spec-First 모드를 설정하고 커밋-앤-푸시 리듬을 따르십시오. 워크플로우를 변경하지 않고 영속성을 원한다면 백업을 켜고 야간 푸시가 처리하도록 하십시오. 많은 팀이 둘 다 사용합니다. 준비가 되면 공급자를 연결하고, 프로젝트를 저장소와 브랜치에 연결하여 API 사양이 나머지 작업이 이미 있는 곳에서 작동하도록 하십시오.