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

요약

Git-native API 워크플레이스란 API 사양이 Git에 진실의 원천(source of truth)으로 저장되며, 완전한 버전 관리, 브랜칭, 그리고 병합 요청(merge request) 워크플로우가 API 개발 플랫폼에 직접 구축되어 있음을 의미합니다. 팀은 격리된 스프린트 브랜치에서 작업하고, 병합 요청을 통해 변경 사항을 검토하며, 리포지토리와 자동으로 동기화됩니다. Apidog의 Spec-first 모드는 OpenAPI 사양 편집을 위한 내장 IDE, 실시간 유효성 검사, 그리고 원활한 GitHub/GitLab/Azure DevOps 통합을 통해 이러한 워크플로우를 제공합니다.

버튼

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

솔직히 말씀드리자면, 몇 년간 API 개발을 이끌면서 모든 팀에서 동일한 협업 문제를 반복적으로 목격했습니다:

"어떤 사양 버전이 현재 사용되는 거지?" — 다섯 명이 같은 Postman 컬렉션을 편집하는데, 아무도 누구의 버전이 권한을 가지는지 모릅니다.
"왜 이 엔드포인트가 바뀌었지?" — 변경 로그도 없고, 이력도 없고, 3개월 전에 매개변수 이름이 왜 바뀌었는지 추적할 방법이 없습니다.
"메인 사양을 망가뜨리지 않고 새로운 기능 작업을 할 수 있을까?" — 모두가 라이브 사양을 함께 편집하거나(혼돈), 파일을 복제하고 나중에 수동으로 병합하는(오류 발생 가능성 높음) 방식입니다.
"이 API 변경 사항을 어떻게 검토하지?" — Slack으로 JSON 스니펫을 보내고, Jira에 스크린샷을 붙여 넣는 등 구조화된 검토 프로세스가 없습니다.

익숙한가요?

이것들은 도구 문제가 아닙니다. 워크플로우 문제입니다. 그리고 이 모든 문제를 해결하는 워크플로우는 무엇일까요? 바로 여러분의 코드 팀이 이미 사용하고 있는 것과 동일합니다: Git.

백엔드 엔지니어들은 Git에서 작업합니다. 프론트엔드 엔지니어들은 Git에서 작업합니다. DevOps 팀도 Git에서 작업합니다. 하지만 어쩐지 API 디자인은 종종 그 세계 밖에 존재하며 — 독점 도구에 갇혀 있고, 다른 모든 것을 움직이는 버전 관리 시스템과 격리되어 있습니다.

이것이 Apidog의 Git-native 접근 방식이 채우는 간극입니다. 이는 여러분의 API 사양을 전체 엔지니어링 조직이 이미 신뢰하는 Git 워크플로우로 가져옵니다.

API에서 "Git-native"란 실제로 무엇을 의미할까요?

Git-native API 개발은 단순히 "OpenAPI 파일을 리포지토리에 저장하는 것"이 아닙니다. 이는 수년 전부터 가능했지만, 팀들은 여전히 동일한 협업의 벽에 부딪혔습니다.

진정한 Git-native는 다음을 의미합니다:

전통적인 Git 저장 방식	Git-Native 워크플레이스
사양은 Git에 있지만 외부 도구에서 편집합니다.	Git을 진실의 원천으로 삼아 플랫폼 내에서 사양을 편집합니다.
다른 곳에서 편집한 후 수동으로 커밋합니다.	API 워크스페이스에서 직접 커밋하고 푸시합니다.
API 브랜칭 개념이 없습니다.	격리된 기능 개발을 위한 스프린트 브랜치를 제공합니다.
코드 검토 도구가 YAML 차이점에 어색하게 적용됩니다.	API 변경 사항에 최적화된 내장 병합 요청을 제공합니다.
누군가 도구의 내부 복사본을 편집하면 동기화가 깨집니다.	Git을 기본으로 존중하는 양방향 동기화를 제공합니다.

차이점은 통합의 깊이입니다. Git-native API 워크플레이스는 리포지토리를 백업 대상이 아닌 권위 있는 원천으로 취급합니다. 편집, 브랜칭, 검토, 테스트 등 모든 것이 Git을 기반으로 이루어집니다.

핵심 구성 요소

Spec-first 모드 — 내부 데이터베이스 레코드가 아닌 OpenAPI YAML/JSON 파일이 주요 아티팩트입니다.
스프린트 브랜치 — 코드의 Git 브랜치처럼 작동하는 API 기능 브랜치입니다.
보호된 메인 브랜치 — 강제된 검토 워크플로우를 통한 프로덕션 안정성입니다.
병합 요청(Merge Requests) — 변경 전후 비교를 통한 구조화된 API 변경 검토입니다.
웹훅 동기화 — 리포지토리에 푸시가 수신될 때 자동 동기화입니다.

이것은 새로운 개념이 아닙니다. 몇 년 전부터 필요했던 도메인에 입증된 Git 워크플로우를 적용하는 것입니다.

전통적인 API 도구의 문제점

대부분의 API 개발 플랫폼은 내부 데이터베이스 모델로 작동합니다:

시각적 양식을 통해 엔드포인트를 생성합니다.
플랫폼은 모든 것을 자체 데이터베이스에 저장합니다.
필요할 때 OpenAPI로 내보냅니다 (종종 불완전하거나 오래된 상태로).
Git 이력을 원하면 수동으로 내보내고 직접 커밋해야 합니다.

이 모델은 개인에게는 잘 작동합니다. 하지만 팀에게는요? 근본적인 마찰을 일으킵니다:

진정한 버전 이력이 없음

플랫폼에 "이력"이 있을 수 있지만, Git 이력은 아닙니다. 다음을 수행할 수 없습니다:

통합된 변경 로그에서 누가 무엇을 언제 변경했는지 확인합니다.
깔끔하게 브랜치하고 병합합니다.
표준 Git 명령을 사용하여 알려진 상태로 롤백합니다.
Git 트리거 워크플로우를 예상하는 CI/CD 파이프라인을 사용합니다.

협업 충돌

여러 개발자가 동일한 프로젝트를 편집할 때:

경고 없이 변경 사항이 서로 덮어쓰여질 수 있습니다.
병합 충돌 해결 메커니즘이 없습니다.
"라이브" 편집은 새로운 기능에 대한 격리가 없음을 의미합니다.

검토의 빈틈

API 변경 사항을 어떻게 검토합니까? 전통적인 도구에서는:

UI 스크린샷
내보낸 JSON 스니펫을 문서에 붙여넣기
구조화된 차이점 보기 없음
감사 추적 기능이 있는 승인 워크플로우 없음

단절

API 사양은 시스템 간의 계약을 설명합니다. 이는 애플리케이션 코드만큼이나 중요합니다. 그러나 다른 모든 것을 보호하는 버전 관리 시스템 밖에 존재합니다. 이러한 단절이 대부분의 API 협업 문제의 근본 원인입니다.

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

Apidog의 Spec-first 모드는 모델을 뒤집습니다: Git이 진실의 원천이 되고, 플랫폼은 Git에 대한 인터페이스가 됩니다.

작동 방식

Spec-first 프로젝트를 생성하면 Apidog은 리포지토리에 직접 연결됩니다:

Git 제공업체 연결 — GitHub, GitLab, Azure DevOps 또는 Bitbucket
리포지토리 및 메인 브랜치 선택 — Apidog은 기존 사양을 읽거나 새로 시작합니다.
Specs 워크스페이스에서 편집 — 구문 강조 기능이 있는 코드 보기, 또는 구조화된 편집을 위한 양식 보기
Apidog에서 커밋 및 푸시 — 변경 사항이 리포지토리로 직접 이동합니다.
웹훅 동기화는 양측을 정렬 상태로 유지합니다 — Git으로 푸시하면 Apidog과 자동으로 동기화됩니다.

Specs 워크스페이스

이곳은 Git-native 경험이 빛을 발하는 곳입니다. 내부 데이터베이스를 업데이트하는 양식을 채우는 대신 파일로 작업합니다:

파일 탐색기 — 리포지토리 구조를 직접 탐색합니다.
API 구조 트리 — 파싱된 OpenAPI 콘텐츠: 엔드포인트, 스키마, 정의
코드 편집기 — 유효성 검사, 자동 완성, 구문 강조 기능이 있는 완전한 IDE 경험
양식 편집기 — 지원되는 노드의 경우, 파일이 원본으로 유지되면서 구조화된 컨트롤을 통해 편집합니다.

원한다면 YAML/JSON으로만 작업할 수 있습니다. 또는 복잡한 엔드포인트 정의를 위해 양식 보기로 전환할 수도 있습니다. 어느 쪽이든 Git의 기본 파일이 중요합니다.

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

편집기에는 다음이 포함됩니다:

유효성 검사 패널 — 구문 오류, 누락된 필수 필드, OpenAPI 규칙 위반이 즉시 감지됩니다.
미리보기 패널 — 커밋하기 전에 사양이 문서로 어떻게 렌더링되는지 확인합니다.
직접 시도해 보기 — 사양 정의에서 직접 엔드포인트를 테스트합니다.

더 이상 손상된 사양을 커밋하고 CI에서 오류를 발견하는 일이 없습니다.

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

코드 개발에서 기능 브랜치는 필수적입니다. 프로덕션 코드를 직접 편집하지 않을 것입니다. 왜 프로덕션 API 사양을 직접 편집해야 할까요?

Apidog의 스프린트 브랜치는 API 작업에 동일한 격리 기능을 제공합니다.

스프린트 브랜치가 가능하게 하는 것

시나리오	스프린트 브랜치 없음	스프린트 브랜치 있음
새로운 엔드포인트 개발	메인 사양을 편집하여 모든 사람의 문서와 테스트를 손상시킬 위험이 있습니다.	격리된 상태에서 작업하고 안정화되면 병합합니다.
API 변경 사항 테스트	모든 테스터가 불완전한 작업 진행 상황을 봅니다.	테스터는 스프린트 브랜치로 전환하여 집중적인 테스트를 수행할 수 있습니다.
병렬 기능 개발	하나의 사양에서 여러 기능이 충돌합니다.	각 기능은 자체 브랜치를 가집니다.
변경 사항 롤백	깔끔한 롤백 메커니즘이 없습니다.	선택적 변경 사항을 삭제하거나 병합합니다.

스프린트 브랜치 생성

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

스프린트 브랜치를 채우는 두 가지 방법

수동 접근 방식 (API-first):

수정해야 할 엔드포인트, 스키마 또는 구성 요소를 복사하려면 메인에서 포크(Fork from main)를 사용합니다. Apidog은 연결을 추적하여 나중에 병합할 때 어떤 리소스가 변경되었는지 알 수 있도록 합니다.

OAS 가져오기 접근 방식 (코드 우선):

백엔드에서 업데이트된 OpenAPI 사양을 가져옵니다. Apidog은 이를 메인 브랜치와 비교하여 변경된 리소스만 가져옵니다. 이렇게 하면 스프린트 브랜치가 실제 차이점에 집중할 수 있습니다.

자동 테스트 매칭

대부분의 팀이 놓치는 것이 있습니다: 스프린트 브랜치에서 엔드포인트를 변경할 때, 기존 테스트는 여전히 메인 브랜치 버전을 대상으로 합니다.

Apidog은 다음을 통해 이 문제를 해결합니다:

테스트 시나리오에서 수정된 엔드포인트 플래그 지정
테스터가 스프린트 브랜치 버전에 맞게 테스트를 복제하고 조정할 수 있도록 함
테스트가 작업 중인 브랜치와 일치하도록 보장

이것은 테스트를 업데이트하지 않고 새 엔드포인트를 병합한 다음 며칠 후에 깨진 CI 파이프라인을 발견하는 일반적인 실패를 방지합니다.

보호된 브랜치와 병합 요청

보호된 브랜치는 프로덕션 안정성의 중추입니다. Apidog에서 보호된 메인 브랜치는 다음을 의미합니다:

직접 편집 불가 — 변경 사항은 병합 요청을 통해 이루어져야 합니다.
필수 검토 — 관리자가 병합 전에 승인합니다.
감사 추적 — 모든 변경 사항에는 검토 기록이 있습니다.

병합 요청 워크플로우

스프린트 브랜치 작업이 준비되면:

브랜치 전환에서 병합(Merge)을 클릭합니다.
색상으로 구분된 상태로 모든 변경 사항을 검토합니다:

회색 — 변경 없음 (병합할 필요 없음)
주황색 — 수정됨 (메인 브랜치와 비교)
녹색 — 새로 생성됨 (스프린트 브랜치에서 생성됨)

수정된 리소스의 경우, 스프린트 버전과 메인 버전 간의 정확한 차이점을 확인합니다.
병합할 항목을 선택합니다.
병합 요청 생성 (보호된 브랜치의 경우) 또는 직접 병합 (보호되지 않은 경우)

검토 프로세스

검토자는 다음을 확인합니다:

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

승인, 거부 또는 수정 요청을 할 수 있습니다. 개발자가 스프린트 브랜치를 업데이트하면 병합 요청에 새 변경 사항이 자동으로 반영됩니다. 새 요청을 만들 필요가 없습니다.

이것은 API 팀이 수년 동안 필요로 했던 검토 워크플로우입니다. 더 이상 스크린샷 기반 검토나 엔드포인트 변경 사항을 설명하려는 Slack 스레드는 없습니다.

원활한 Git 통합: 커밋, 푸시, 풀

Git 작업은 Apidog 내에서 직접 이루어집니다. 외부 Git 클라이언트가 필요 없습니다.

커밋 및 푸시

편집 후:

변경 사항(Changes)을 클릭하여 수정, 추가, 삭제된 파일을 검토합니다.
포함할 파일을 선택합니다.
커밋 메시지를 작성합니다.
푸시(Push)를 클릭하면 변경 사항이 리포지토리에 즉시 동기화됩니다.

Git 풀

팀원들이 연결된 리포지토리에 변경 사항을 푸시할 때:

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

웹훅 동기화 (권장)

리포지토리 관리자 권한이 있는 경우, 설정 중에 웹훅을 설치합니다:

리포지토리로 푸시하면 Apidog 자동 동기화가 트리거됩니다.
수동으로 풀할 필요가 없습니다.
팀은 노력 없이 정렬된 상태를 유지합니다.

웹훅 동기화 없이도 수동 풀은 잘 작동합니다. 하지만 웹훅 동기화는 "최신 사양을 누가 가지고 있지?"라는 질문을 완전히 없앱니다.

무엇이 달라졌는가 vs 전통적인 워크플로우

이전	이후
개발자가 메인 사양을 직접 편집합니다.	격리된 스프린트 브랜치
테스터는 불완전한 변경 사항을 테스트할 수 없습니다.	테스트 전용 브랜치
스크린샷 및 Slack 스레드를 통한 검토	차이점이 있는 구조화된 병합 요청
병렬 작업에 대한 가시성 없음	브랜치 전환으로 모든 활성 작업 표시
병합 시 자동 덮어쓰기	미리보기와 함께 선택적 병합

이것은 복잡성을 추가하는 것이 아닙니다. 혼돈을 제거하는 구조를 추가하는 것입니다.

자주 묻는 질문 (FAQ)

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

Spec-first 모드는 Git 리포지토리를 진실의 원천(source of truth)으로 사용합니다. 일반 Apidog 프로젝트는 Apidog의 내부 데이터베이스를 기본으로 사용하며, Git 내보내기는 보조적인 기능입니다. Spec-first 모드에서는 파일을 직접 편집하고, Apidog에서 Git으로 커밋하며, 자동으로 동기화됩니다. 일반 모드에서는 양식을 통해 편집하며, Git 내보내기는 수동 또는 예약된 방식입니다.

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

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

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

Apidog은 Spec-first 프로젝트를 위해 GitHub, GitLab, Azure DevOps, Bitbucket을 지원합니다. 프로젝트 생성 중에 이러한 제공업체 중 하나에서 리포지토리를 연결할 수 있습니다.

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

웹훅 설치에는 관리자 권한이 필요하며, 이는 리포지토리에 푸시가 수신될 때 자동 동기화를 가능하게 합니다. 웹훅 동기화 없이도 수동 Git 풀을 사용하여 변경 사항을 동기화할 수 있습니다. Apidog에서 변경 사항을 푸시하는 데는 쓰기 권한이면 충분합니다.

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

네. 리포지토리에 기존 OpenAPI 파일이 없는 경우, Apidog은 새로 시작합니다. Specs 워크스페이스에서 사양을 생성하고 리포지토리로 푸시합니다. 첫 번째 커밋이 사양의 기반을 구축합니다.

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

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

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

웹훅 동기화가 설치되어 있는 경우, Git으로 푸시하면 Apidog으로 자동 동기화가 트리거됩니다. Apidog에서 작업 중인데 누군가 Git으로 푸시하면, 보류 중인 업데이트를 나타내는 동기화 상태가 표시됩니다. Git 풀을 사용하여 해당 변경 사항을 Apidog으로 가져올 수 있습니다.

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

네. Specs 워크스페이스에는 직접 YAML/JSON 편집을 위한 코드 편집기와 지원되는 OpenAPI 노드(엔드포인트, 스키마, 정의)를 위한 양식 보기가 포함되어 있습니다. 필요에 따라 뷰를 전환할 수 있습니다. 두 가지 모두 Git의 기본 파일을 업데이트합니다.

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

테스트 시나리오는 엔드포인트 및 스키마와 별도로 병합됩니다. API 리소스를 메인 브랜치에 병합한 후, 스프린트 브랜치의 테스트 시나리오에 마우스를 올리고 메인으로 병합(Merge to Main)을 선택합니다. 현재 프로젝트 관리자만 테스트 시나리오를 보호된 메인 브랜치에 병합할 수 있습니다.

버튼