실전 고수 팁 — Spring REST Docs 기반 API 명세 자동화

Swagger는 코드와 문서가 쉽게 어긋납니다. Spring REST Docs는 MockMvc 테스트가 통과할 때만 문서(스니펫)가 생성되므로, 테스트와 API 문서가 항상 동기화됩니다.

1. 의존성 설정

testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'

2. 테스트에서 문서 스니펫 생성

@WebMvcTest(UserController.class)
@AutoConfigureRestDocs(outputDir = "build/generated-snippets") // 스니펫 저장 경로
class UserControllerDocTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean
    private UserService userService;

    @Test
    void 회원_조회_API_문서화() throws Exception {
        given(userService.getUser(1L)).willReturn(new UserDto(1L, "홍길동", "hong@test.com"));

        mockMvc.perform(get("/api/users/{id}", 1L)
                .accept(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andDo(document("get-user",        // 스니펫 폴더명
                pathParameters(
                    parameterWithName("id").description("사용자 식별자")
                ),
                responseFields(
                    fieldWithPath("id").description("사용자 ID"),
                    fieldWithPath("name").description("사용자 이름"),
                    fieldWithPath("email").description("이메일 주소")
                )
            ));
    }
}

테스트 실행 시 build/generated-snippets/get-user/ 하위에 http-request.adoc, http-response.adoc, path-parameters.adoc 등의 Asciidoc 스니펫 파일이 자동 생성됩니다.

3. API 문서 조립 (index.adoc)

= API 명세서
:toc: left

== 회원 API

=== 회원 단건 조회

==== HTTP 요청
include::{snippets}/get-user/http-request.adoc[]

==== 요청 파라미터
include::{snippets}/get-user/path-parameters.adoc[]

==== HTTP 응답
include::{snippets}/get-user/http-response.adoc[]

==== 응답 필드
include::{snippets}/get-user/response-fields.adoc[]

빌드 시 (./gradlew asciidoctor) 아름다운 HTML API 문서가 자동으로 생성되어 팀 전체와 공유할 수 있습니다.