API Spec-as-Code 전환을 통한 Contract 정합성 확보 및 Git-native 워크플로우 구축

Context

Wiki나 공유 드라이브 기반의 API 문서 관리로 인한 변경 이력 추적 불가 및 버전 불일치 문제 발생. 이로 인해 Client 단의 런타임 오류와 Mock 서버의 최신화 누락 등 API Contract 불일치에 따른 개발 생산성 저하 직면.

Technical Solution

• OpenAPI Spec을 소스 코드와 동일한 Artifact로 취급하여 Git Repository 내 api/ 경로에 통합 관리하는 Spec-as-Code 구조 설계
• Major Version별 파일 분리(api-v1.yaml, api-v2.yaml)를 통한 하위 호환성 유지 및 Diff 분석 효율 최적화
• api/ 프리픽스를 활용한 Branching 전략 수립으로 Contract 변경 사항에 대한 가시성 확보 및 PR 기반의 Peer Review 강제
• CI Pipeline 내 oasdiff 등 도구를 통합하여 Breaking Change 자동 탐지 및 빌드 실패 처리를 통한 계약 위반 원천 차단
• Visual Editor(Apidog)와 Git 간의 양방향 동기화를 통해 YAML 수동 편집의 휴먼 에러 제거 및 일관된 포맷팅 유지

Key Takeaway

API 문서를 단순한 설명서가 아닌 시스템의 '계약서(Contract)'로 정의하고, 소프트웨어 형상 관리 프로세스를 적용함으로써 배포 전 단계에서 Interface 정합성을 검증하는 구조적 안전장치 마련 가능