백엔드
Swagger 기반 API 명세 자동화 PoC
두줄요약
고객사 환경 제약 때문에 Swagger를 서비스에 직접 붙이지 않고, 중앙 서버와 YAML 파일로 API 명세를 통합하는 PoC를 검증했습니다. 또한 Custom Annotation 기반으로 배포 시점에 명세를 자동 생성하는 확장 방향도 살펴봤습니다.
문제 상황
- 고객사 환경 제약으로 서비스별 Swagger 라이브러리 직접 적용이 어려운 상황
- 수동 API 문서 작성과 최신화 지연으로 전사 개발팀 간 VOC 발생
- 배포된 API 목록과 request, response 구조를 Swagger UI에서 통합 조회할 필요
해결 방법
- 각 서비스에 Swagger를 직접 붙이지 않고 중앙 Swagger 서버에서 여러 YAML 명세를 통합 제공하는 구조 검증
- 외부 디렉터리의 YAML 파일을 정적 리소스로 복사해 SwaggerResourcesProvider로 동적 등록
- Custom Annotation과 reflection 기반 분석으로 requestBody, response VO를 읽어 YAML 생성하는 라이브러리화 방향 검토
구조와 흐름
- swagger-apis, swagger-demo, swagger-file-generator로 역할 분리
- 개발팀 프로젝트 → 공통 생성 라이브러리 → 중앙 Swagger 서버 → Swagger UI 흐름 구성
- YAML 기반 통합 조회와 공통 명세 생성 책임 분리를 통한 운영 단순화
주의할 점
- 외부 명세 저장소 경로를 상대 경로로 두면 실행 위치에 영향
- 문자열 조립 방식의 YAML 생성은 구조 복잡도 증가 시 오류 가능성 존재