Rihpig

Posted on Jun 12 • Originally published at apidog.com

깃 네이티브 API 개발 환경: 팀 API 개발 확장 비법

요약: Git-native API 워크플레이스는 API 사양을 Git에 진실의 원천(source of truth)으로 저장하고, 버전 관리, 브랜칭, 병합 요청(Merge Request) 워크플로우를 API 개발 플랫폼 안에서 직접 실행하는 방식입니다. 팀은 격리된 스프린트 브랜치에서 작업하고, 병합 요청으로 변경 사항을 검토하며, 리포지토리와 자동 동기화할 수 있습니다. Apidog의 Spec-first 모드는 OpenAPI 사양 편집용 IDE, 실시간 유효성 검사, GitHub/GitLab/Azure DevOps 통합을 통해 이 워크플로우를 제공합니다.

오늘 Apidog을 사용해 보세요

API 팀에 Git-native 워크플로우가 필요한 이유

API 협업에서 자주 발생하는 문제는 대부분 도구 문제가 아니라 워크플로우 문제입니다.

예를 들어 다음과 같은 상황입니다.

“현재 기준이 되는 API 사양은 어떤 버전이지?”

여러 명이 같은 컬렉션이나 문서를 수정하지만, 어떤 버전이 권한 있는 버전인지 불명확합니다.
“이 엔드포인트는 왜 변경됐지?”

변경 이력, 작성자, 변경 이유를 추적하기 어렵습니다.
“메인 사양을 깨뜨리지 않고 새 기능을 설계할 수 있을까?”

라이브 사양을 직접 수정하거나, 복사본을 만든 뒤 나중에 수동 병합해야 합니다.
“API 변경 사항을 어떻게 리뷰하지?”

Slack 메시지, JSON 스니펫, 스크린샷에 의존하게 됩니다.

코드 개발에서는 이미 Git이 이 문제를 해결합니다. 백엔드, 프론트엔드, DevOps 팀은 브랜치, 커밋, 리뷰, 병합을 사용합니다. 하지만 API 디자인은 여전히 별도 도구 안에 고립되는 경우가 많습니다.

Git-native API 워크플로우의 핵심은 API 사양도 코드처럼 Git 중심으로 관리하는 것입니다.

API에서 “Git-native”란 무엇인가요?

Git-native API 개발은 단순히 OpenAPI 파일을 Git 리포지토리에 저장하는 것이 아닙니다.

진짜 Git-native 워크플로우는 다음을 포함합니다.

전통적인 Git 저장 방식	Git-native API 워크플레이스
사양은 Git에 있지만 외부 도구에서 편집합니다.	Git을 진실의 원천으로 삼고 플랫폼 안에서 사양을 편집합니다.
수정 후 수동으로 커밋합니다.	API 워크스페이스에서 직접 커밋하고 푸시합니다.
API 브랜칭 개념이 없습니다.	기능 개발을 위한 스프린트 브랜치를 제공합니다.
코드 리뷰 도구로 YAML diff를 어렵게 확인합니다.	API 변경 사항에 최적화된 병합 요청을 제공합니다.
도구 내부 복사본과 Git이 쉽게 어긋납니다.	Git 기준의 양방향 동기화를 제공합니다.

Git-native API 워크플레이스는 리포지토리를 백업 대상이 아니라 권위 있는 원천으로 다룹니다. 편집, 브랜칭, 리뷰, 테스트가 모두 Git을 기준으로 동작합니다.

핵심 구성 요소

Spec-first 모드

OpenAPI YAML/JSON 파일이 기본 아티팩트입니다.
스프린트 브랜치

코드의 Git 브랜치처럼 API 변경을 격리합니다.
보호된 메인 브랜치

프로덕션 API 사양을 직접 수정하지 못하도록 제한합니다.
병합 요청

변경 전후를 비교하고 리뷰 후 병합합니다.
웹훅 동기화

Git 리포지토리에 푸시가 발생하면 Apidog과 자동 동기화합니다.

전통적인 API 도구의 한계

많은 API 도구는 내부 데이터베이스를 중심으로 동작합니다.

일반적인 흐름은 다음과 같습니다.

UI에서 엔드포인트를 생성합니다.
도구가 자체 데이터베이스에 데이터를 저장합니다.
필요할 때 OpenAPI로 내보냅니다.
Git 이력이 필요하면 내보낸 파일을 직접 커밋합니다.

개인 작업에는 충분할 수 있지만, 팀 협업에서는 다음 문제가 생깁니다.

1. 진짜 Git 이력이 없음

도구 내부에 변경 이력이 있더라도 Git 이력과는 다릅니다.

다음 작업이 어렵습니다.

누가, 언제, 무엇을 변경했는지 Git 로그로 확인
브랜치 기반 병렬 작업
특정 커밋으로 롤백
Git 이벤트 기반 CI/CD 실행

2. 협업 충돌

여러 개발자가 같은 API 사양을 수정하면 다음 문제가 발생할 수 있습니다.

변경 사항이 서로 덮어써짐
병합 충돌을 구조적으로 해결하기 어려움
메인 사양에 미완성 기능이 노출됨

3. 리뷰 프로세스 부족

API 변경 리뷰가 다음 방식으로 흘러가기 쉽습니다.

UI 스크린샷 공유
JSON/YAML 조각을 문서에 붙여넣기
Slack 스레드에서 변경 설명
승인 기록 없이 구두 합의

API 사양은 서비스 간 계약입니다. 애플리케이션 코드처럼 버전 관리와 리뷰가 필요합니다.

Apidog의 Git-native 접근 방식: Spec-first 모드

Apidog의 Spec-first 모드는 Git 리포지토리를 진실의 원천으로 사용합니다. Apidog은 Git 위에서 API 사양을 편집하고 리뷰하는 인터페이스 역할을 합니다.

기본 설정 흐름

Spec-first 프로젝트를 만들 때는 다음 순서로 진행합니다.

Git 제공업체 연결

GitHub, GitLab, Azure DevOps 또는 Bitbucket을 연결합니다.
리포지토리와 메인 브랜치 선택

기존 OpenAPI 사양을 읽거나 빈 리포지토리에서 시작합니다.
Specs 워크스페이스에서 편집

코드 보기 또는 양식 보기로 OpenAPI 파일을 수정합니다.
Apidog에서 커밋 및 푸시

변경 사항을 Git 리포지토리에 직접 반영합니다.
웹훅으로 자동 동기화

Git에 푸시된 변경 사항을 Apidog과 동기화합니다.

Specs 워크스페이스에서 할 수 있는 작업

Specs 워크스페이스는 파일 기반으로 동작합니다.

파일 탐색기

리포지토리 구조를 그대로 탐색합니다.
API 구조 트리

OpenAPI의 엔드포인트, 스키마, 정의를 파싱해 보여줍니다.
코드 편집기

YAML/JSON을 직접 수정할 수 있습니다.
양식 편집기

지원되는 OpenAPI 노드는 구조화된 폼으로 편집할 수 있습니다.

YAML/JSON만으로 작업해도 되고, 복잡한 엔드포인트는 양식 보기로 전환해 수정할 수도 있습니다. 어느 쪽이든 Git의 OpenAPI 파일이 기준입니다.

실시간 유효성 검사와 미리보기

편집 중 다음을 바로 확인할 수 있습니다.

유효성 검사 패널

구문 오류, 필수 필드 누락, OpenAPI 규칙 위반을 감지합니다.
미리보기 패널

커밋 전에 문서 렌더링 결과를 확인합니다.
직접 시도해 보기

사양에 정의된 엔드포인트를 바로 테스트합니다.

이렇게 하면 깨진 OpenAPI 사양을 커밋한 뒤 CI에서 뒤늦게 발견하는 상황을 줄일 수 있습니다.

스프린트 브랜치: API 기능 브랜치

코드 개발에서 기능 브랜치를 쓰는 것처럼 API 사양도 메인 브랜치를 직접 수정하지 않는 것이 안전합니다.

Apidog의 스프린트 브랜치는 API 변경을 격리하는 기능 브랜치입니다.

스프린트 브랜치가 필요한 상황

시나리오	스프린트 브랜치 없음	스프린트 브랜치 있음
새 엔드포인트 개발	메인 사양을 직접 수정해 문서와 테스트가 깨질 수 있습니다.	격리된 브랜치에서 작업 후 안정화되면 병합합니다.
API 변경 테스트	모든 테스터가 미완성 변경 사항을 보게 됩니다.	테스터가 해당 브랜치로 전환해 집중 테스트할 수 있습니다.
병렬 기능 개발	여러 기능이 하나의 사양에서 충돌합니다.	기능별 브랜치로 분리합니다.
변경 사항 롤백	수동 되돌리기가 필요합니다.	브랜치 변경 사항을 선택적으로 폐기하거나 병합합니다.

스프린트 브랜치 생성 절차

APIs 옆의 브랜치 전환 버튼을 클릭합니다.
새 스프린트 브랜치를 선택합니다.
기능 이름을 입력합니다. 예: user-authentication-v2
메인 브랜치와 격리된 상태에서 API를 수정합니다.

스프린트 브랜치에 변경 사항을 추가하는 방법

방법 1: API-first 방식

수정할 엔드포인트, 스키마, 구성 요소를 메인에서 가져옵니다.

Apidog에서는 메인에서 포크(Fork from main) 를 사용해 리소스를 복사할 수 있습니다. 이후 병합 시 어떤 리소스가 변경되었는지 추적할 수 있습니다.

방법 2: OAS 가져오기 방식

백엔드에서 생성된 OpenAPI 사양을 가져옵니다.

Apidog은 이를 메인 브랜치와 비교해 변경된 리소스만 반영합니다. 코드 우선(code-first) 방식으로 API를 관리하는 팀에 유용합니다.

테스트도 브랜치에 맞춰야 합니다

엔드포인트를 스프린트 브랜치에서 변경했는데 테스트가 여전히 메인 브랜치 사양을 기준으로 실행되면 문제가 생깁니다.

Apidog은 다음 방식으로 이를 줄입니다.

테스트 시나리오에서 수정된 엔드포인트를 표시
스프린트 브랜치 버전에 맞게 테스트를 복제 및 조정
API 변경과 테스트 변경을 같은 작업 흐름에서 관리

보호된 브랜치와 병합 요청

보호된 메인 브랜치는 프로덕션 API 사양을 안정적으로 유지하기 위한 장치입니다.

Apidog에서 보호된 브랜치를 사용하면 다음을 적용할 수 있습니다.

직접 편집 불가

변경은 병합 요청을 통해서만 반영됩니다.
필수 리뷰

관리자가 병합 전에 승인합니다.
감사 추적

모든 변경 사항에 리뷰 기록이 남습니다.

병합 요청 워크플로우

스프린트 브랜치 작업이 끝나면 다음 순서로 병합합니다.

브랜치 전환 메뉴에서 병합(Merge) 을 클릭합니다.
변경 사항을 상태별로 확인합니다.

회색: 변경 없음
주황색: 수정됨
녹색: 새로 생성됨

수정된 리소스의 변경 전후 차이를 확인합니다.
병합할 항목을 선택합니다.
보호된 브랜치라면 병합 요청 생성, 보호되지 않은 브랜치라면 직접 병합을 선택합니다.

리뷰어가 확인하는 내용

리뷰어는 다음을 확인할 수 있습니다.

전체 변경 목록
수정된 리소스의 변경 전/후 비교
스프린트 브랜치의 작업 컨텍스트

리뷰어는 승인, 거부, 수정 요청을 할 수 있습니다. 개발자가 스프린트 브랜치를 업데이트하면 기존 병합 요청에 변경 사항이 반영됩니다.

Git 통합: 커밋, 푸시, 풀

Apidog에서는 외부 Git 클라이언트 없이도 기본 Git 작업을 수행할 수 있습니다.

커밋 및 푸시

편집 후 변경 사항(Changes) 을 엽니다.
수정, 추가, 삭제된 파일을 확인합니다.
커밋에 포함할 파일을 선택합니다.
커밋 메시지를 작성합니다.
푸시(Push) 를 클릭해 리포지토리에 반영합니다.

Git 풀

다른 팀원이 리포지토리에 변경 사항을 푸시했다면 다음과 같이 가져옵니다.

Specs 사이드바에서 브랜치 이름을 클릭합니다.
Git 풀(Git Pull) 을 선택합니다.
최신 파일을 Apidog으로 동기화합니다.

웹훅 동기화

리포지토리 관리자 권한이 있다면 설정 중 웹훅을 설치하는 것이 좋습니다.

웹훅을 사용하면 다음이 가능합니다.

Git 리포지토리에 푸시 발생 시 Apidog 자동 동기화
수동 풀 작업 감소
팀 전체가 최신 사양을 기준으로 작업

웹훅 없이도 수동 풀은 가능하지만, 자동 동기화는 “누가 최신 사양을 가지고 있나?”라는 문제를 줄여줍니다.

기존 워크플로우와 비교

이전	이후
개발자가 메인 사양을 직접 수정	격리된 스프린트 브랜치에서 작업
테스터가 미완성 변경 사항을 바로 보게 됨	테스트 전용 브랜치 사용
스크린샷과 Slack으로 리뷰	diff 기반 병합 요청
병렬 작업 가시성 부족	브랜치 전환으로 활성 작업 확인
병합 시 덮어쓰기 위험	변경 사항 선택 후 병합

FAQ

Spec-first 모드와 일반 Apidog 프로젝트의 차이는 무엇인가요?

Spec-first 모드는 Git 리포지토리를 진실의 원천으로 사용합니다. OpenAPI 파일을 직접 편집하고, Apidog에서 Git으로 커밋 및 푸시하며, 리포지토리와 동기화합니다.

일반 Apidog 프로젝트는 Apidog의 내부 데이터베이스를 기본으로 사용하고, Git 내보내기는 보조 기능으로 동작합니다.

기존 Apidog 프로젝트를 Spec-first 모드로 전환할 수 있나요?

현재 Spec-first 모드는 Git 리포지토리에 연결된 새 프로젝트 생성이 필요합니다. 기존 프로젝트의 OpenAPI 사양을 내보낸 뒤 새 Spec-first 프로젝트로 가져와 마이그레이션할 수 있습니다.

어떤 Git 제공업체를 지원하나요?

Apidog은 Spec-first 프로젝트에서 GitHub, GitLab, Azure DevOps, Bitbucket을 지원합니다.

리포지토리에 관리자 권한이 필요한가요?

웹훅 설치에는 관리자 권한이 필요합니다. 웹훅은 리포지토리에 푸시가 발생할 때 자동 동기화를 트리거합니다.

웹훅을 사용하지 않는 경우에도 수동 Git 풀로 변경 사항을 동기화할 수 있습니다. Apidog에서 변경 사항을 푸시하려면 쓰기 권한이 필요합니다.

빈 리포지토리로 Spec-first 모드를 사용할 수 있나요?

네. 리포지토리에 기존 OpenAPI 파일이 없어도 시작할 수 있습니다. Specs 워크스페이스에서 새 사양을 생성하고 첫 커밋으로 리포지토리에 푸시하면 됩니다.

스프린트 브랜치는 Git 브랜치와 어떻게 다른가요?

Apidog의 스프린트 브랜치는 리포지토리의 Git 브랜치에 해당합니다. Apidog에서 스프린트 브랜치를 만들면 Git에도 해당 브랜치가 생성됩니다. 스프린트 브랜치의 변경 사항은 연결된 Git 브랜치와 동기화됩니다.

누군가 Git 리포지토리를 직접 편집하면 어떻게 되나요?

웹훅 동기화가 설정되어 있으면 Git으로 푸시된 변경 사항이 Apidog으로 자동 동기화됩니다.

Apidog에서 작업 중인 상태에서 리포지토리에 새 변경 사항이 생기면 동기화 상태를 확인하고 Git 풀로 가져올 수 있습니다.

코드 보기와 양식 보기 모두에서 사양을 편집할 수 있나요?

네. Specs 워크스페이스에서는 YAML/JSON을 직접 편집하는 코드 보기와, 지원되는 OpenAPI 노드를 구조화된 폼으로 수정하는 양식 보기를 사용할 수 있습니다. 두 방식 모두 Git의 기본 파일을 업데이트합니다.

테스트 시나리오에 대한 병합 요청은 어떻게 동작하나요?

테스트 시나리오는 엔드포인트 및 스키마와 별도로 병합됩니다. API 리소스를 메인 브랜치에 병합한 뒤, 스프린트 브랜치의 테스트 시나리오에서 메인으로 병합(Merge to Main) 을 선택합니다.

현재 프로젝트 관리자만 테스트 시나리오를 보호된 메인 브랜치에 병합할 수 있습니다.

DEV Community