회사에서 Spring REST Docs를 적용해볼 수 있는 기회가 생길 수 있어서 미리 정리해보고자 공식 문서를 정리해봤다. 우선 정리부터 시작하지만 혼자 적용부터 회사에도 적용해 볼 수 있으면 좋겠다...
Spring REST Docs 공식 문서를 번역하여 정리한 내용입니다.
• 개요
Spring REST Docs는 RESTful API의 문서화를 자동화하고 정확성을 보장하는 도구다.
• 주요 특징
- 테스트 기반 문서화:
Spring MVC Test, WebFlux의 WebTestClient, 또는 REST Assured5를 사용한 테스트 코드에서 문서 스니펫을 생성한다.
이는 테스트 주도 개발(TDD)의 원칙을 문서화에도 적용한 것이다. - 자동 생성 + 수동 작성의 결합:
테스트에서 자동으로 생성된 스니펫과 개발자가 수동으로 작성한 문서를 결합한다.
이 방식은 문서의 정확성과 상세도를 모두 확보할 수 있게 해주는 장점이 있다. - 유연한 출력 형식:
기본적으로 Asciidoctor를 사용하여 HTML 문서를 생성한다.
필요에 따라 Markdown 사용도 가능하다.
• 기술적 이점
- 문서의 정확성 보장:
테스트가 실패하면 관련 스니펫 생성도 실패합니다. 이는 API의 변경사항이 즉시 문서에 반영됨을 의미한다. (실제 구현과 문서 간의 불일치를 방지) - 구현과 문서의 분리:
API의 내부 구현 세부사항이 아닌, 외부에 노출되는 인터페이스(HTTP 요청/응답)에 초점을 둔다. (사용자에게 필요한 정보만 제공하고 내부 구현 변경 시 문서 수정의 필요성을 줄임) - 리소스 중심 문서화:
RESTful 서비스의 각 리소스에 대해 HTTP 요청과 HTTP 응답을 중심으로 문서화한다. (REST 아키텍처의 원칙에 부합하는 문서화)
• 개발 프로세스에 미치는 영향
- 테스트 코드 품질 향상
문서화를 위해 더 철저한 테스트 케이스 작성이 요구되므로, 전반적인 테스트 커버리지와 품질이 향상될 수 있다. - API 설계 개선:
문서화 과정에서 API의 일관성, 사용성 등을 자연스럽게 검토하게 되어 전반적인 API 설계 품질이 향상될 수 있다. - 지속적 통합/배포(CI/CD) 용이성:
테스트 실행 시 자동으로 최신 문서가 생성되므로, CI/CD 파이프라인에 쉽게 통합할 수 있다.
• 사용 시 고려사항
- Asciidoctor 문법, 테스트 코드 작성 방식 등에 대한 지식이 필요할 수 있다.
- 초기 설정 복잡성:
프로젝트에 Spring REST Docs 통합하는 초기 설정이 다소 복잡하다. - 테스트 실행 시간 증가:
문서 생성을 위한 추가적인 테스트로 인해 전체 테스트 실행 시간이 증가할 수 있다.
구현 방법
• 최소 요구 사항
o Java 17
o Spring Framework 6
o spring-restdocs-restassured 모듈은 REST Assured 5.2 필요• 빌드
plugins{
id "org.asciidoctor.jvm.convert" version "3.3.2" // 1
}
configurations {
asciidoctorExt // 2
}
dependencies {
asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' // 3
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' // 4
}
ext {
snippetsDir = file('build/generated-snippets') // 5
}
test { // 6
outputs.dir.snippetsDir
}
asciidoctor { // 7
inputs.dir snippetsDir // 8
configurations 'asciidoctorExt' // 9
dependsOn test // 10
}
bootJar { // 11
dependsOn asciidoctor // 12
from ("${asciidoctor.outputDir}/html5") { // 13
into 'static/docs' // 14
}
}- Asciidoctor 플러그인 적용:
Asciidoctor를 사용하기 위한 기반 - asciidoctorExt 구성 선언:
Asciidoctor의 기능을 확장하는 플러그인이나 라이브러리 관리 - spring-restdocs-asciidoctor 의존성 추가:
Spring REST Docs와 Asciidoctor 연동 - spring-restdocs-mockmvc 의존성 추가:
MockMvc를 사용하여 API 테스트를 작성하고 문서화할 수 있다. 필요에 따라 WebTestClient나 REST Assured로 대체 - snippetsDir 속성 구성:
테스트 실행 시 생성되는 문서의 저장 - test 태스크 출력 설정:
Gradle이 테스트 실행 결과물(스니펫)의 위치를 인식하여 불필요한 재빌드를 방지한다. - asciidoctor 태스크 구성:
AsciiDoc 문서를 최종 출력 형식(ex.HTML)으로 변환하는 과정을 제어한다. - asciidoctor 태스크 입력 설정
o Gradle이 스니펫 디렉토리의 변경을 감지하여, 필요한 경우에만 문서를 재생성한다. - asciidoctorExt 구성 사용 설정:
Spring REST Docs의 Asciidoctor 확장 기능 활성화 - test 의존성 추가:
테스트 실행되게 하는 의존성 - 문서 패키징 추가:
생성한 API문서를 프로젝트의 JAR 파일에 포함 시키는 설정 (jar 가 빌드 되기 전에 문서를 생성해야 함 / jar에 생성한 문서가 있어야 함) - bootJar가 실행되기 전에 asciidoctor가 먼저 실행되도록 의존성 설정
- 생성된 문서를 jar의 static/docs 디렉토리에 복사
