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

컬리 신규 입사자가 선물하기 시스템을 재개발하며 API 문서화 도구로 Spring REST Docs를 택한 이유와, 정적 문서의 아쉬움을 Swagger UI 결합으로 보완한 과정을 다룬다. Swagger(Springdoc)와의 장단점 비교가 중심이다.

핵심 포인트

Swagger는 상세 정보를 넣을수록 운영코드에 애노테이션이 침투하는 반면, Spring REST Docs는 테스트 작성을 강제해 문서 신뢰도를 높인다.
Springdoc은 기본 설정만으로 Swagger-UI를 렌더링하지만, 풍부한 정보를 주려면 결국 애노테이션을 운영코드에 넣어야 한다.
Spring REST Docs는 테스트 실행으로 Asciidoc 스니펫을 만들어 asciidoctor로 HTML을 조합하며, API 변경 시 누락을 테스트가 즉시 잡는다.
정적 문서의 단점은 restdocs-api-spec으로 OpenAPI(OAS) 문서를 생성해 Swagger-UI로 동적 확인하도록 보완했다.

상세 정리

배경: Wiki 문서로 된 기존 API 문서가 탐탁치 않아 선물하기 재개발 때 Spring REST Docs로 전환했고, 예제 프로젝트를 별도로 공개했다.
도구 선택지: Java REST 문서화 도구로 Swagger, Spring REST Docs, RAML이 있으며 RAML은 사실상 제외된다.
Swagger 침투성: Springfox는 2020년 이후 활동이 없어 Springdoc을 권하지만, Springdoc도 기본 제공 정보는 밋밋해 상세화하려면 스웨거 애노테이션이 운영코드로 침투한다.
Springdoc 기본 동작: springdoc-openapi-ui 의존성만 추가하면 swagger-ui.html 경로로 UI를 볼 수 있고, 애노테이션 없이도 컨트롤러 클래스명을 케밥 태그로, 파라미터 클래스를 스키마로 추출한다.
REST Docs 원리: 문서에 포함될 스니펫을 얻으려면 반드시 테스트를 작성해야 하며, 스니펫에 오류가 있으면 테스트가 실패해 서비스 안정성을 보장한다.
테스트 프레임워크: Spring MVC Test, WebFlux WebTestClient, REST Assured로 테스트를 작성해 스니펫을 생성하고 asciidoctor로 HTML로 렌더한다.
커스텀 스니펫 함정: 사용자 정의 스니펫은 src/test/resources/org/springframework/restdocs/templates/asciidoctor 경로에 둬야 하는데, IntelliJ에서 패키지 표기(점)로 등록하면 적용이 안 될 수 있어 버전별 경로 확인이 필요하다.
로컬 테스트 보안: 문서에서 API를 직접 호출하려면 CORS·CSRF·FrameOption을 비활성화해야 하는데, 반드시 local/dev/stage 프로파일에서만 적용하도록 WebSecurityConfig를 분리했다.
Swagger 결합: restdocs-api-spec으로 테스트 코드를 거의 공유하면서 OAS(openapi3.yaml)를 생성, MockMvcRestDocumentationWrapper.document로 REST Docs 스니펫과 OAS를 동시에 만든다.
패키징: bootJar 태스크에서 build/docs/asciidoc 산출물과 openapi3.yaml을 jar 정적 리소스로 포함해, 스프링 부트 정적 파일 지원으로 Swagger-UI와 문서를 함께 서빙한다.
결론: 두 도구는 각자 장단점이 있어 엔지니어가 선택할 문제지만, 테스트로 신뢰감을 높인다는 점에서 저자는 Spring REST Docs를 권한다.