기업 사례사례
원본으로 →토스의 사내 Swagger MCP 서버 — Spring-AI로 API 스펙 공유 자동화
반복되는 API 스펙 공유를 없애기 위해 Spring-AI로 Swagger MCP 서버를 구축한 과정과 겪은 문제들
노
노예1호2026.03.05조회 83
★ 0.0 (0명)|내 평가
로그인 이후 사용할 수 있습니다
로그인 이후 사용할 수 있습니다
요약
API를 개발하면 Swagger에서 링크를 찾아 메신저로 공유하고, 스펙이 변경되면 다시 공유해야 합니다. 토스에서 이 반복을 없애기 위해 LLM이 Swagger에 직접 접근하는 MCP 서버를 Spring-AI로 구축한 과정에 대한 글입니다.
인사이트
- 대량 API를 가진 서버의 전체 스펙을 LLM에 넣으면 토큰 초과 에러 발생 — 미사용 API 제거, JSON 가공, API 그루핑 기반 페이징으로 해결
- SSE 방식은 서버 배포·연결 끊김 시 세션이 유실되어 사용 불가 — Stateless Streamable HTTP로 전환 후 안정화
- LLM이 MCP 서버를 호출하지 않는 경우가 빈번 — Prompt를 별도로 등록하여 호출을 유도해야 함
해결
1. Stateless Streamable HTTP + ASYNC 모드 선택
- SSE/일반 Streamable HTTP는 세션 유실 문제로 부적합, MSA 환경에 맞는 Stateless 방식 채택
- 네트워크 I/O가 많아 ASYNC 모드 적용
2. 4단계 API 스펙 조회 구조
- Step 1: SwaggerCenter에서 전체 서비스 목록 조회
- Step 2: 특정 서비스의 API 목록을 가공하여 반환 (URL, Method, summary만)
- Step 3: 특정 API의 상세 스펙 (parameters, requestBody, responses) 추출
- Step 4: $ref 참조 컴포넌트 스키마 별도 조회
3. Swagger 작성 자동화 (GitHub Actions)
- Controller 파일 변경 감지 → Gemini AI로 @Tag, @Operation 애너테이션 자동 추가 → PR에 코멘트
참고
Spring-AI 1.1.0-M3(Pre-release) 기반 개발이며, Swagger 컴포넌트 이름 충돌(springdoc.use-fqn=true), ArgumentResolver 파라미터 노출 문제 등 실무 트러블슈팅도 포함되어 있습니다.
댓글 0
로그인 이후 사용할 수 있습니다