Rihpig

Posted on Jun 2 • Originally published at apidog.com

OpenAPI 스펙 깃허브 동기화 두 가지 방법

OpenAPI 문서가 Git 저장소에 있는데 API 클라이언트 안에서 따로 편집하고 있다면, 사양과 저장소를 계속 수동으로 맞춰야 합니다. YAML을 복사하고 다시 붙여넣고, 가져오기 과정에서 필드가 누락되지 않았는지 확인하는 작업은 쉽게 실수로 이어집니다. 이 글에서는 Apidog의 Spec-First 모드로 OpenAPI 사양을 GitHub와 양방향 동기화하는 방법을 단계별로 정리합니다. 저장소의 OpenAPI 파일을 Apidog에서 직접 열고, YAML을 수정하고, 변경 사항을 GitHub 브랜치로 커밋 및 푸시하는 흐름입니다. 동일한 방식은 GitLab에서도 사용할 수 있습니다.

지금 Apidog 사용해 보기

양방향 동기화가 실제로 의미하는 것

양방향 동기화는 OpenAPI 사양 변경 사항이 Git과 Apidog 사이에서 내보내기 없이 오간다는 뜻입니다.

Apidog → Git: Apidog에서 OpenAPI 문서를 수정한 뒤 커밋하면, 변경 사항이 선택한 브랜치에 일반 Git 커밋으로 푸시됩니다.
Git → Apidog: 팀원이 저장소에서 같은 브랜치에 변경 사항을 푸시하면, Apidog이 이를 가져와 편집기 상태를 최신 저장소 내용과 맞춥니다.

즉, 저장소가 단일 진실 공급원입니다. Apidog은 그 위에서 OpenAPI를 편집하고 검증하는 인터페이스 역할을 합니다. 이 흐름은 Git-네이티브 API 워크플로의 핵심입니다. 사양은 별도 도구에 갇혀 있는 스냅샷이 아니라, 코드베이스의 다른 파일처럼 버전 관리되고 리뷰되며 이력이 남습니다.

사전 준비 사항

시작하기 전에 다음을 확인하세요.

Apidog 데스크톱 앱 또는 웹 버전에 로그인되어 있어야 합니다.
OpenAPI 문서를 포함한 GitHub 또는 GitLab 저장소가 있어야 합니다.
동기화할 브랜치에 대한 쓰기 권한이 있어야 합니다.
Spec-First 모드(베타)를 사용할 수 있어야 합니다.
Azure DevOps는 Git Connection을 통해 사용할 수 있습니다.

읽기 전용 권한만 있으면 가져오기는 가능하지만 커밋 및 푸시는 할 수 없습니다.

1단계: Git 공급자 연결

먼저 Apidog이 Git 공급자에 접근할 수 있도록 인증합니다.

Apidog을 엽니다.
새 프로젝트를 만들 때 Spec-First 모드를 선택합니다.
소스 선택 화면에서 GitHub 또는 GitLab을 선택합니다.
승인을 클릭합니다.
브라우저에서 열린 OAuth 화면에서 Apidog에 저장소 접근 권한을 부여합니다.
GitHub를 사용하는 경우, 필요하면 전체 계정이 아니라 특정 저장소로 권한 범위를 제한합니다.

승인이 끝나면 Apidog으로 돌아오고 공급자 연결이 완료됩니다. 이 작업은 공급자당 한 번만 수행하면 되며, 이후 프로젝트에서는 기존 연결을 재사용할 수 있습니다.

Git Connection 및 Azure DevOps를 포함한 자세한 설정은 Spec-First 모드 문서를 참고하세요.

2단계: 저장소와 브랜치에서 프로젝트 생성

이제 Apidog 프로젝트가 실제 OpenAPI 파일을 가리키도록 설정합니다.

연결된 공급자에서 OpenAPI 파일이 있는 저장소를 선택합니다.
동기화할 브랜치를 선택합니다. 일반적으로 main을 사용하지만, 보호 브랜치라면 작업용 브랜치를 선택하는 것이 좋습니다.
Apidog이 요청하면 OpenAPI 문서 경로를 지정합니다.
- 예: openapi.yaml
- 예: docs/openapi.yaml
프로젝트를 생성합니다.

Apidog은 선택한 브랜치에서 사양 파일을 가져와 엽니다. 이후 OpenAPI 문서를 파싱하고, 왼쪽 사이드바에 엔드포인트와 스키마를 탐색 가능한 구조로 표시합니다.

이 시점부터 Apidog에서 보는 문서는 저장소의 OpenAPI 파일과 연결된 상태입니다.

3단계: 코드 편집기에서 OpenAPI YAML 편집

Spec-First 모드는 원시 OpenAPI YAML을 직접 수정할 수 있는 IDE 스타일 편집기를 제공합니다.

지원되는 편집 기능은 다음과 같습니다.

구문 강조
인라인 유효성 검사
자동 완성
OpenAPI 구조 개요 자동 갱신

예를 들어 상태 확인용 엔드포인트를 추가하려면 다음과 같이 작성할 수 있습니다.

paths:
  /health:
    get:
      summary: Service health check
      operationId: getHealth
      responses:
        '200':
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: ok

편집하는 동안 Apidog은 다음을 즉시 반영합니다.

왼쪽 사이드바에 /health 작업 표시
누락된 responses 블록 감지
잘못된 $ref 표시
YAML 들여쓰기 오류 표시
OpenAPI 구조 오류 인라인 표시

즉, CI 파이프라인에서 실패를 확인하기 전에 편집 단계에서 문제를 바로 찾을 수 있습니다.

OpenAPI 변경 이력과 diff 관리에 대해 더 자세히 보려면 Git을 사용한 OpenAPI 버전 제어 가이드를 참고하세요.

4단계: 커밋 및 푸시

수정 내용이 준비되면 GitHub로 커밋하고 푸시합니다.

Apidog의 Git 또는 소스 제어 영역에서 커밋 패널을 엽니다.
변경 사항 diff를 검토합니다.
커밋 메시지를 입력합니다.

Add /health endpoint

Commit & Push를 클릭합니다.

Apidog은 선택한 브랜치에 커밋을 만들고 원격 저장소로 푸시합니다. GitHub에서 저장소를 열면 브랜치 이력에 해당 커밋이 나타나고, OpenAPI 파일에 변경 사항이 적용된 것을 확인할 수 있습니다.

커밋하기 전에 실험한 내용을 취소하고 싶다면 푸시되지 않은 편집 내용을 버리면 됩니다. Commit & Push를 실행하기 전까지 변경 사항은 원격 저장소에 반영되지 않습니다.

5단계: 동기화 상태 확인

Apidog은 동기화 상태 표시기를 통해 현재 상태를 보여줍니다.

푸시가 성공하면 표시기는 편집기와 원격 브랜치가 같은 문서를 보고 있음을 알려줍니다. 시간이 지나면 마지막 동기화 시간이 갱신되고, 다른 사용자가 같은 브랜치에 변경 사항을 푸시하면 Apidog이 이를 가져와 상태를 다시 맞춥니다.

동기화 표시기가 보류 중이거나 오래된 상태를 나타낸다면 다음 중 하나를 확인하세요.

원격 브랜치에 새로운 커밋이 있는지
로컬 편집 내용이 아직 커밋되지 않았는지
충돌이 발생했는지
인증 권한이 만료되었는지

문제 해결

인증이 만료되었거나 취소된 경우

푸시 중 권한 오류가 발생하면 Git 공급자 인증을 다시 실행하세요. OAuth 토큰은 공급자 측에서 취소되거나 만료될 수 있습니다.

잘못된 브랜치에 연결한 경우

보호된 main 브랜치에 직접 푸시하려고 하면 거부될 수 있습니다.

이 경우 다음 중 하나를 선택하세요.

작업용 브랜치와 동기화
브랜치 보호 규칙 조정
pull request 기반 워크플로 사용
Apidog 프로젝트가 올바른 브랜치를 바라보는지 확인

병합 충돌이 발생한 경우

작업 중 팀원이 같은 브랜치의 같은 파일을 수정했다면 충돌이 발생할 수 있습니다.

해결 흐름은 일반 Git 충돌과 동일합니다.

최신 원격 변경 사항을 가져옵니다.
겹치는 YAML 영역을 확인합니다.
충돌 내용을 정리합니다.
유효성 검사를 통과하는지 확인합니다.
다시 커밋하고 푸시합니다.

OpenAPI 사양은 일반 텍스트 파일이므로 코드 충돌을 해결하는 방식과 동일하게 처리할 수 있습니다.

유효성 검사 오류가 표시되는 경우

Apidog은 인라인으로 YAML 및 OpenAPI 구조 문제를 표시합니다. 커밋 전에 다음을 확인하세요.

responses가 누락되지 않았는지
$ref 경로가 올바른지
YAML 들여쓰기가 정확한지
스키마 타입이 올바른지
경로와 메서드 구조가 OpenAPI 형식에 맞는지

깨끗한 사양을 유지하면 생성된 문서, mock, 테스트 결과도 더 안정적으로 유지됩니다.

자주 묻는 질문

GitHub 동기화 흐름이 GitLab 및 Azure DevOps에서도 작동합니까?

예. Spec-First 모드는 GitHub 및 GitLab을 직접 지원하며, Azure DevOps는 Git Connection을 통해 지원합니다. 연결, 편집, 커밋, 푸시 흐름은 동일하고 인증 화면만 공급자별로 다릅니다.

제가 Apidog에서 작업하는 동안 팀원이 저장소에서 사양을 편집하면 어떻게 됩니까?

Apidog은 양방향 동기화의 일부로 원격 변경 사항을 다시 가져옵니다. 변경 영역이 다르면 병합됩니다. 같은 YAML 영역을 수정했다면 일반 텍스트 파일처럼 Git 충돌을 해결해야 합니다.

GitHub에 반영되기 전에 변경 사항을 취소할 수 있습니까?

예. Commit & Push를 클릭하기 전까지 변경 사항은 로컬에만 있습니다. 푸시되지 않은 편집 내용을 버리면 문서를 마지막 동기화 상태로 되돌릴 수 있고, 원격 저장소에는 아무것도 반영되지 않습니다.

DEV Community