아키텍처
채널톡 Open API 뜯어고치기
두줄요약
문서와 API 계약 불일치를 해결하기 위해 OAS 중심 Design-first와 Open API 서버를 도입했습니다. 내부 모델을 분리하고 문서·코드·번역·MCP 연동을 하나의 명세로 관리했습니다.
문제 상황
- 가이드 문서와 코드 생성 Swagger UI의 경로·예시·설명 불일치
- Java 내부 모델의 직접 직렬화로 인한 공개 API 계약 변동과 내부 필드 노출 위험
- 문서 문구 수정에도 메인 서버 재배포와 평균 일주일의 반영 주기 필요
선택 이유
- 구현 전 공개 입력·응답 계약 검토와 고객 연동 준비가 가능한 Design-first 채택
- OAS를 문서·코드 생성·설명·예시의 단일 기준으로 운영
- AppStore 호출 체계 통합 대신 기존 고객 전환 비용을 고려한 REST 방식 유지
구조와 흐름
- OAS에서 oapi-codegen 기반 Go 타입·서버 인터페이스 생성 후 구현 연결
- Go 기반 Open API 서버가 여러 Core API 결과를 조합해 고객용 REST 응답 구성
- 내부 비즈니스 모델, proto 기반 공개 리소스 모델, OAS 최종 JSON 응답 모델의 경계 분리
성능/운영 포인트
- API Key 검증과 Rate Limit은 Open API 서버, 리소스 규칙·권한은 Core API 담당
- OAS·영문·국문 번역 파일 비교와 생성 결과 차이 검사를 CI에 포함
- 85개 REST API 공개 후 문서 Try it, MCP 호출, 문서 기반 AI 질의 연동
