10/19

Today I Learned

REST API를 구축하면서 가장 중요한 작업 중 하나는 API 문서를 작성하는 것이다.

하지만 문서를 수동으로 작성하면 번거롭고, 실제 API와 불일치할 가능성도 높다.

이런 문제를 해결하기 위한 방법 중 하나가 바로 Spring Rest Docs다.

Spring Rest Docs란?

Spring Rest Docs는 Spring MVC 기반 애플리케이션을 위한 API 문서화를 자동화하는 라이브러리이다.

테스트 코드와 연동되어 API의 입력/출력을 기반으로 문서 스니펫을 생성하며,항상 최신 상태의 문서를 유지할 수 있다는 점이 가장 큰 장점이다.

 

주요 특징

테스트 코드 기반 문서화: 테스트가 성공해야 문서가 생성된다.

Asciidoctor 형식 사용: `.adoc` 문서를 HTML/PDF로 변환 가능하다.

스니펫(snippets) 기반 모듈화: 요청/응답/파라미터 등을 분리된 문서 조각으로 관리

프로젝트 설정

1. Gradle 의존성 추가

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

2. Asciidoctor 설정

plugins {
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
}

asciidoctor {
    inputs.dir snippetsDir
    dependsOn test
}

→ 테스트 실행 후 `build/generated-snippets` 경로에 문서 조각들이 생성된다.

흐름 예시: 사용자 조회 API 문서화

1. 테스트 코드 작성

mockMvc.perform(get("/api/v1/users/{id}", 1L))
    .andExpect(status().isOk())
    .andDo(document("get-user",
        pathParameters(
            parameterWithName("id").description("사용자 ID")
        ),
        responseFields(
            fieldWithPath("id").description("사용자 고유 ID"),
            fieldWithPath("name").description("사용자 이름"),
            fieldWithPath("email").description("사용자 이메일")
        )
    ));

2. Asciidoctor 문서 작성 (`index.adoc`)

= 사용자 API 문서

== 사용자 조회

include::{snippets}/get-user/path-parameters.adoc[]
include::{snippets}/get-user/response-fields.adoc[]

3. HTML 문서 출력

./gradlew asciidoctor

→ `build/docs/ascidoc/index.html` 경로에 문서 생성됨

 

마무리

Spring REST Docs는 테스트 기반 문서화 라는 철학을 가진 도구다.

문서 품질과 정확성을 중요하게 생각한다면 도입해 볼 가치가 충분하다고 느꼈다.

API 변경이 생겨도 테스트만 수정하면 문서도 자동으로 최신화되니, 문서 관리의 번거로움을 줄이는 데도 효과적이라 생각된다.