아키텍처
커뮤니티실 API Design-First 접근방식 정착기
두줄요약
커뮤니티실이 노션 중심 수동 API 설계에서 OAS 기반 Design-First 방식으로 전환한 과정을 소개했습니다.명세 자동 생성과 모델 재사용으로 효율과 일관성을 높였지만, 명세 관리 부담도 함께 짚었습니다.
핵심 내용
- 커뮤니티실의 API 설계 방식이 노션 중심 수동 명세에서 OAS 기반 Design-First 방식으로 전환된 과정 정리
- OpenAPI Specification으로 명세를 별도 저장소에서 관리하고, PR 검토 후 openapi-generator와 GitHub Actions로 서버·클라이언트 코드를 자동 생성
- 명세와 코드의 강결합, 모델 재사용, 일관된 협업 용어로 개발 효율과 최신성 향상
장단점
- 노션 방식은 소규모에서 빠른 논의에 유리했지만, 표준 부재와 명세 파편화, 수동 모델 작성으로 비효율 증가
- OAS 방식은 체계적 관리와 자동 생성에 강점이 있으나, 명세 실수 전파와 오너십 경계 모호성, 명세 확정 지연 같은 부담 존재
적용해볼 점
- API 명세를 코드 생성 가능한 규격으로 관리해 수작업과 불일치 최소화
- 모델 중심으로 서버·클라이언트가 같은 용어를 공유하는 협업 구조 고려
- 별도 저장소와 PR 기반 검토, 자동 생성 워크플로우 도입 검토