Spring REST Docs란?

API 문서를 테스트 기반으로 자동 생성해주는 도구이다. Swagger처럼 어노테이션 기반이 아니라, 실제 API 요청/응답을 테스트하면서 정확한 문서 조각을 생성하는 게 특징이다.

❓왜 사용할까?

벡엔드와 프론트엔드 협업 시 신뢰할 수 있는 API 명세서를 제공한다.
테스트 코드 작성만으로 문서를 자동화할 수 있어서 생산성이 증가한다.
문서와 실제 API가 100% 일치하므로 실수가 줄어든다.
Swagger UI처럼 실시간 테스트는 안되지만, 정적 문서(PDF, HTML 등)로 깔끔하게 관리 가능하다.

특징

항목	내용
문서 생성 방식	테스트 기반
문서 형태	정적 HTML, PDF
UI 제공	없음
정확도	테스트 통과된 실제 API 기준
주로 사용처	공공 프로젝트, 기업 내부 시스템 등

🔄️작동 방식

1. @WebMvcTest 또는 @SpringBootTest로 테스트 환경 구성
   Spring REST Docs는 테스트 기반 문서화 도구이기 때문에 먼저 MockMvc를 사용할 수 있는 테스트 환경을 구성해야 한다. 보통 컨트롤러 단 테스트에선 @WebMvcTest, 전체 문서 구성 시엔 @SpringBootTest를 사용한다.

2. 테스트 코드에서 .andDo(document("문서이름")) 호출
   MockMvc를 통해 API 요청을 테스트한 후 .andDo(document("user-create")) 와 같이 호출하면 해당 테스트의 요청/응답 정보가 문서로 저장된다. 이때 requestFields, responseFields, pathParameters, requestParameters 등을 추가하면
   요청/응답 구조를 명확하게 설명할 수 있다.

3. build/generated-snippets/ 경로에 문서 조각 생성
   테스트가 실행되면, 테스트 이름에 해당하는 문서 조각(Snippet) 들이 build/generated-snippets/ 폴더 아래에 자동으로 생성된다. 이 안에는 요청 본문, 응답 본문, HTTP 상태, 헤더 등 다양한 정보가 .adoc 파일 형태로 쪼개져 있다.

4. 문서 본문(index.adoc)에서 조각 파일들을 include로 조립
   src/docs/asciidoc/index.adoc 파일을 만들어 위에서 생성된 조각들을 조립한다.

5. Gradle로 Asciidoctor task 실행 -> 최종 문서 생성
   build.gradle에 asciidoctor 플러그인을 설정하면 Gradle 빌드 시 자동으로 조립된 문서가 build/docs/asciidoc/index.html로 생성된다. 이 HTML 문서를 브라우저에서 열면 실제 문서화된 API 명세서를 확인할 수 있다.

예시 코드

mockMvc.perform(post("/users")
        .contentType(MediaType.APPLICATION_JSON)
        .content("{\"email\": \"test@email.com\", \"password\": \"1234\"}"))
    .andExpect(status().isOk())
    .andDo(document("user-create", 
        requestFields(
            fieldWithPath("email").description("사용자 이메일"),
            fieldWithPath("password").description("비밀번호")
        )
    ));

위 테스트를 실행하면 "user-create" 문서 조각이 자동 생성된다.

🔎Swagger와의 차이점

항목	Swagger	Spring REST Docs
문서화 방식	어노테이션 기반	테스트 기반
실시간 테스트	가능(UI)	불가능(정적 문서)
정확성	코드 수정 시 누락 가능	테스트 기반이라 실제 API와 일치
보안성	UI 노출 우려 있음	내부 문서로 안전함

📝배운점

Spring REST Docs는 테스트와 문서화를 동시에 관리할 수 있어서 실제 서비스에 신뢰도 높은 문서가 필요할 때 적합한 도구라고 느꼈다. Swagger보다 진입장벽이 있긴 히지만 한 번 익숙해지면 훨씬 안정적인 문서 자동화가 가능하다는 생각이 들었다.