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

OpenAPI 문서가 Git 저장소에 있지만 API 클라이언트 내에서 편집하는 경우, 불편함을 이미 알고 계실 것입니다. YAML을 복사하고, 다시 붙여넣고, 다른 사람이 파일을 건드리지 않았기를 바라고, 가져오기 과정에서 필드가 조용히 누락되지 않았기를 기도해야 합니다. 사양과 저장소를 수동으로 일치시키는 것은 바쁠 때 정확히 문제가 발생하는 종류의 번거로운 작업입니다. 이 가이드는 Apidog의 Spec-First 모드를 사용하여 OpenAPI 사양을 GitHub와 동기화하는 방법을 보여줍니다. 이렇게 하면 저장소의 사양과 편집기 내의 사양이 끊임없이 조율해야 하는 두 개의 복사본이 아니라 동일한 상태를 유지합니다. 공급자를 연결하고, 저장소에서 직접 프로젝트를 열고, YAML을 편집하고, 변경 사항을 한 번에 GitHub로 다시 푸시할 것입니다. 동일한 단계가 GitLab에서도 작동합니다. 시작해 봅시다. button

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

양방향 동기화는 중간에 내보내기 단계 없이 양방향으로 자동으로 편집 내용이 흘러간다는 것을 의미합니다.

Apidog에서 Git으로: Apidog에서 OpenAPI 문서를 편집하고 커밋하면, 변경 사항은 선택한 브랜치에 일반적인 Git 커밋으로 저장소에 푸시됩니다.
Git에서 Apidog으로: 팀원(또는 IDE에서 직접)이 해당 브랜치에 변경 사항을 푸시하면, Apidog이 이를 다시 가져와서 편집기가 실제로 저장소에 있는 내용을 반영하도록 합니다.

저장소가 단일 진실 공급원입니다. Apidog은 그 위에 있는 풍부한 편집기입니다. 이것이 Git-네이티브 API 워크플로의 전체 아이디어입니다. 사양은 주기적으로 스냅샷을 내보내는 도구에 머무는 대신, 코드베이스의 다른 파일처럼 버전 관리되고, 검토되며, 이력이 추적됩니다.

사전 준비 사항

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

Apidog이 설치되어 있고(데스크톱 앱 또는 웹), 로그인되어 있습니다.
이미 OpenAPI 문서를 포함하고 있거나 쓰기 권한이 있는 GitHub 또는 GitLab 저장소가 있습니다. Azure DevOps는 Git Connection을 통해 지원됩니다.
Spec-First 모드(베타)가 활성화되어 있습니다. 이 모드는 프로젝트를 Apidog 자체 저장소 대신 Git 저장소 위에 얇은 레이어로 전환합니다.

동기화하려는 브랜치에 대한 쓰기 권한이 필요합니다. 읽기 전용 액세스는 가져오기만 허용하고 푸시는 허용하지 않습니다.

1단계: Git 공급자 연결

먼저, Apidog이 공급자와 통신하도록 권한을 부여합니다.

Apidog을 열고 Spec-First 모드를 선택하여 새 프로젝트를 생성합니다.
소스를 선택하라는 메시지가 표시되면 GitHub 또는 GitLab 공급자를 선택합니다.
승인을 클릭합니다. 브라우저에 공급자의 OAuth 화면이 열립니다.
Apidog에 동기화하려는 저장소에 대한 액세스 권한을 부여합니다. GitHub에서는 전체 계정 대신 특정 저장소로 범위를 지정할 수 있습니다.

승인이 완료되면 Apidog으로 돌아와 공급자가 연결됩니다. 이 작업은 공급자당 한 번만 수행하면 되며, 향후 프로젝트에서는 연결을 재사용합니다. Git Connection을 통한 Azure DevOps를 포함하여 이 흐름에 대한 전체 참조는 Spec-First 모드 문서를 참조하세요.

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

이제 Apidog이 실제 사양을 가리키도록 합니다.

공급자가 연결된 상태에서 OpenAPI 파일을 포함하는 저장소를 선택합니다.
동기화할 브랜치를 선택합니다. 일반적으로 main입니다. 이 브랜치는 커밋이 적용될 브랜치이며 Apidog이 들어오는 변경 사항을 감시하는 브랜치입니다.
Apidog이 묻는다면 OpenAPI 문서의 경로를 확인합니다(예: 저장소 루트의 openapi.yaml 또는 docs/ 아래).
프로젝트를 생성합니다.

Apidog은 해당 브랜치에서 사양을 복제하여 엽니다. Apidog이 문서를 탐색 가능한 개요로 파싱했으므로 왼쪽 사이드바에 엔드포인트와 스키마가 채워집니다. 이제 저장소의 사양을 실시간으로 보고 있는 것입니다.

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

Spec-First 모드는 구문 강조, 인라인 유효성 검사, 자동 완성 기능을 갖춘 원시 OpenAPI YAML용 IDE 스타일 편집기를 제공합니다. OpenAPI를 직접 작성하면 Apidog은 입력하는 대로 시각적 개요를 유지합니다. 작은 엔드포인트를 추가해 봅시다. 상태 확인이 필요하다고 가정해 봅시다.

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

입력하는 동안 두 가지 일이 발생합니다. 왼쪽 사이드바는 개요를 자동으로 파싱하여 새로운 /health 작업이 즉시 트리에 나타납니다. 그리고 유효성 검사기는 커밋하기 전에 누락된 responses 블록, 잘못된 $ref, 들여쓰기 오류와 같은 문제를 인라인으로 표시합니다. YAML이 잘못 구성된 경우 나중에 파이프라인 실패에서 발견하는 대신 밑줄이 표시되는 것을 볼 수 있습니다. 또한 여기서 버전 제어가 중요한 역할을 합니다. 사양에 대한 diff와 이력이 어떻게 작동하는지에 대해 더 자세히 살펴보려면 Git을 사용한 OpenAPI 버전 제어 가이드를 참조하세요.

4단계: 커밋 및 푸시

편집 내용이 올바르게 보이면 GitHub로 보냅니다.

커밋 패널(프로젝트의 Git/소스 제어 영역)을 엽니다.
변경 사항을 검토합니다. Apidog은 동기화된 버전과 비교하여 수정된 내용을 보여줍니다.
커밋 메시지를 작성합니다. 일반적인 커밋처럼 다룹니다: Add /health endpoint.
Commit & Push를 클릭합니다.

Apidog은 선택한 브랜치에 커밋하고 원격으로 푸시합니다. GitHub에서 저장소를 열면 브랜치 기록에서 예상대로 작성된 커밋이 OpenAPI 파일에 정확히 적용된 것을 볼 수 있습니다. 푸시하기 전에 마음이 바뀌었나요? 푸시되지 않은 편집 내용을 버려 문서를 마지막 동기화 상태로 되돌릴 수 있습니다. 커밋하기 전까지는 아무것도 Apidog을 떠나지 않으므로 로컬 실험은 로컬에 남아 있습니다.

5단계: 동기화 상태 확인

Apidog은 동기화 표시기를 통해 현재 상태를 항상 알 수 있도록 합니다. 푸시가 성공한 후 표시기는 "지금 동기화됨"이라고 표시됩니다. 이는 편집기와 원격 브랜치가 동일한 문서를 보유하고 있다는 확인입니다. 시간이 지남에 따라 업데이트되고("5분 전 동기화됨"), 다른 사람이 푸시하면 Apidog이 변경 사항을 가져와 조정한 후 표시기를 재설정합니다. 표시기가 보류 중이거나 오래된 상태를 나타내면 로컬 복사본과 원격 복사본이 분기되었음을 알려주는 것이므로 계속하기 전에 가져오거나 해결해야 합니다.

문제 해결

몇 가지 사항은 처음 사용하는 사람들을 헷갈리게 할 수 있습니다.

인증 만료 또는 취소됨. 권한 오류로 푸시가 실패하기 시작하면 1단계에서 인증을 다시 실행합니다. 토큰은 공급자 측에서 취소되거나 단순히 시간이 초과될 수 있습니다.
잘못된 브랜치. 풀 리퀘스트를 요구하는 보호된 main으로 푸시하면 거부됩니다. 해시 브랜치와 동기화하거나 브랜치의 보호 규칙을 조정하세요. 2단계에서 선택한 브랜치가 커밋이 적용될 것으로 예상되는 곳과 일치하는지 다시 확인하세요.
병합 충돌. 편집하는 동안 팀원이 동일한 브랜치에 푸시한 경우 원격이 로컬 복사본보다 앞서갔습니다. 최신 내용을 가져오고, 겹치는 YAML을 조정하고, 다시 커밋하세요. 사양은 일반 텍스트이므로 모든 코드 충돌과 동일한 방식으로 충돌이 해결됩니다.
유효성 검사 오류가 흐름을 방해합니다. Apidog은 유효하지 않은 YAML을 커밋하는 것을 막지는 않지만, 인라인 유효성 검사기가 표시하는 내용을 먼저 수정해야 합니다. 깨끗한 사양은 생성된 문서, 모의 및 테스트를 정확하게 유지합니다.

자주 묻는 질문

GitHub와의 동기화가 GitLab 및 Azure DevOps에서도 작동합니까?

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

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

Apidog은 양방향 동기화의 일부로 그들의 변경 사항을 편집기로 다시 가져옵니다. 귀하의 편집 내용과 그들의 편집 내용이 파일의 다른 부분을 건드린다면 깔끔하게 병합됩니다. 겹치는 경우 일반 텍스트 파일에서처럼 표준 Git 충돌을 해결하게 될 것입니다.

GitHub에 도달하기 전에 변경 사항을 실행 취소할 수 있습니까?

예. Commit & Push를 클릭하기 전까지는 편집 내용이 로컬에 있습니다. 푸시되지 않은 편집 내용을 버려 문서를 마지막 동기화 상태로 되돌리면 원격에는 아무것도 도달하지 않습니다. button