API Contract를 Source Code로 관리하는 Git-native 설계 기반 동기화 최적화

How Do You Design and Develop APIs the Git-Native Way?

Hassann2026년 6월 3일12분intermediate

AI 요약

Context

코드 구현 후 명세서를 생성하는 사후 처리 방식으로 인해 Specification과 실제 Implementation 간의 Drift 발생. 벤더 종속적인 Cloud DB 기반 설계 도구 사용으로 인한 버전 관리 부재 및 변경 이력 추적의 어려움 직면.

API Definition을 Plain Text(.yaml, .json) 파일로 변환하여 Repository 내 직접 관리하는 Git-native 구조 채택
Branch-Commit-PR-Merge로 이어지는 표준 Git Workflow를 API 설계 프로세스에 이식하여 설계 단계의 Peer Review 강제
Main Branch의 Spec 파일을 Single Source of Truth로 정의하고 Mock, Doc, Client를 해당 파일에서 자동 생성하는 Downstream 파이프라인 구축
Breaking Change 발생 시 break/api- 브랜치 접두사 사용 및 CODEOWNERS를 통한 승인 절차 도입으로 변경 제어
CI 파이프라인 내 Contract Test를 통합하여 서버 응답과 Committed Spec 간의 불일치 시 Build Fail 처리하는 검증 로직 구현
Spec과 Implementation 코드를 동일 Repo에 Co-location 하여 단일 PR 내에서 계약과 핸들러를 동시 업데이트하는 원자적 변경 구조 설계

실천 포인트

1. API 명세서를 외부 툴이 아닌 Repo 내 텍스트 파일로 이전했는가

2. API 변경 사항이 PR 단계를 통해 리뷰되고 메인 브랜치에 반영되는가

3. CI 단계에서 Spec과 실제 API 응답을 검증하는 Contract Test가 포함되었는가

4. Spec 파일 변경 시 관련 Client와 Mock이 자동으로 갱신되는 파이프라인이 존재하는가

태그