피드로 돌아가기
컬리 기술블로그Backend
원문 읽기
컬리 기술블로그내가 만든 API를 널리 알리기 - Spring REST Docs 가이드편
컬리가 Wiki 기반 API 문서를 Spring REST Docs로 전환해 테스트 강제와 함께 코드 변경에 대한 즉각적 검증 체계 구축
AI 요약
Context
기존 Wiki 형식의 API 문서는 운영 코드와 분리되어 있어 API 변경 시 문서 동기화가 보장되지 않았다. Swagger를 사용하면 운영 코드에 @ApiOperation, @ApiParam 등의 애노테이션을 침투적으로 삽입해야 했으며, 상세한 정보를 제공할수록 운영 코드 복잡도가 증가했다.
Technical Solution
- Spring REST Docs 도입: Spring MVC Test 프레임워크로 HTTP 요청/응답을 검증하는 테스트 코드 작성 후 자동으로 Asciidoc 스니펫 생성
- 테스트 강제 메커니즘: API 문서에 포함되는 스니펫은 테스트 실행을 통해서만 생성되므로 테스트 코드 작성이 필수
- 스니펫 조합 및 HTML 렌더링: Asciidoctor 플러그인을 이용해 자동 생성된 스니펫과 개발자 작성 Asciidoc을 조합해 정적 HTML 문서로 변환
- 사용자정의 스니펫: src/test/resources/org/springframework/restdocs/templates/asciidoctor 경로에 스니펫 템플릿을 정의해 기본 포맷 커스터마이징
- JAR 패키징 포함: Gradle bootJar 태스크 구성으로 build/docs/asciidoc과 build/api-spec 디렉터리의 생성물을 BOOT-INF/classes/static 경로에 포함시켜 실행 가능한 JAR에서 정적 리소스로 제공
Key Takeaway
API 문서 신뢰성을 테스트 코드로 강제하면 코드 변경 시 누락된 필드나 응답값을 즉시 감지할 수 있으며, 운영 코드에 애노테이션 침투를 방지하면서 장기 유지보수성을 확보할 수 있다.
실천 포인트
Spring 기반 REST API를 제공하는 팀에서 Spring REST Docs를 도입할 때, Spring Web과 Test 프레임워크를 필수 스택으로 갖추고 HTTP 요청/응답 검증 테스트를 작성하면 운영 코드를 오염시키지 않으면서도 항상 최신 상태의 API 문서를 자동 생성할 수 있다.