커뮤니티실 API Design-First 접근방식 정착기

이 게시물은 커뮤니티실 그룹 플랫폼팀에서 API 설계 방식을 노션 기반에서 OpenAPI Specification(OAS) 기반의 Design-First 접근으로 전환한 경험을 소개합니다.

과거와 변화

• 노션을 이용한 API 명세 작성은 빠르고 가벼웠으나, 대규모 서비스에서 비효율과 명세 신뢰도 저하 문제 발생
• OAS 도입으로 YAML/JSON 포맷 기반 API 명세 작성과 openapi-generator를 활용해 코드 자동 생성
• GitHub 저장소와 PR 기반 관리로 명세 변경 이력 추적과 협업 효율성 향상

OAS 도입의 장점과 고려사항

• 공유 모델 정의를 통해 API 수정 시 일괄 반영 가능, 서버와 클라이언트 간 원활한 소통 지원
• 명세와 코드가 강결합되어 최신성 유지
• 명세 작성 부담과 오너십 경계 모호, 협의에 소요되는 시간 증가는 숙제로 남음