내가 만든 API를 널리 알리기 - Spring REST Docs 가이드편

Kurly(Kurly)는 선물하기 시스템 재개발 프로젝트에서 기존 Wiki 기반 API 문서를 Spring REST Docs 기반으로 전환했다. 초기에는 Swagger(Springdoc)와 Spring REST Docs 중 선택이 필요했으나, Swagger 애노테이션이 운영 코드에 침투하는 문제를 피하고 테스트 작성을 강제하여 서비스 안정성을 확보하기 위해 Spring REST Docs를 채택했다.

Spring REST Docs는 테스트 코드를 실행해 Asciidoc 스니펫을 생성하고 이를 HTML 문서로 렌더링하는 방식이다. 테스트가 없으면 문서가 생성되지 않으므로 API 변경 시 누락된 필드나 응답값을 즉각 확인할 수 있다는 장점이 있다. 반면, 정적인 HTML 문서만으로는 기획자나 운영자가 API를 직접 테스트하기 어렵다는 한계가 있었다.

Swagger UI 통합을 통한 테스트 편의성 확보

이러한 한계를 극복하기 위해 ePages-de/restdocs-api-spec 라이브러리를 활용해 OpenAPI Specification(OAS) 문서를 JSON 또는 YAML 형식으로 생성하는 방식을 도입했다. 기존 테스트 코드를 공유하여 OAS 문서를 생성하고, 이를 Swagger UI에 연동함으로써 문서 내에서 직접 API 요청 및 응답을 테스트할 수 있게 되었다.

• build.gradle 설정을 통해 생성된 openapi3.yaml 파일을 정적 리소스로 포함
• Swagger UI 접근 경로 설정 및 CORS, CSRF 비활성화(개발 환경 전용) 적용
• Postman 등 외부 도구에서도 생성된 YAML 파일을 활용해 API 테스트 가능

이 접근법은 운영 코드의 침투를 최소화하면서도, 테스트 기반의 신뢰성 있는 문서와 시각적으로 편리한 테스트 인터페이스를 동시에 제공하는 해결책이 되었다.