Spring Rest Docs는 REST API 문서를 자동으로 생성해 주는 Spring 하위 프로젝트이다.
Spring Rest Docs의 가장 큰 특징은 Controller의 슬라이스 테스트를 통해 테스트가 통과 되어야지만 API 문서가 정상적으로 만들어 진다는 것이다.
passed
"이면 다음 작업을 진행하고, "failed
"이면 문제를 해결하기 위해 테스트 케이스를 수정한 후 다시 테스트를 진행해야 한다.passed
"이면 테스트 코드에 포함된 API 스펙 정보 코드를 기반으로 API 문서 스니핏이 .adoc
확장자를 가진 파일로 생성된다.Spring Rest Docs가 API 문서 생성 작업을 정상적으로 수행할 수 있도록 기본적인 설정 작업을 먼저 해 주어야 한다.
plugins {
id 'org.springframework.boot' version '2.7.1'
id 'io.spring.dependency-management' version '1.0.11.RELEASE'
id "org.asciidoctor.jvm.convert" version "3.3.2" // (1)
id 'java'
}
...
...
repositories {
mavenCentral()
}
// (2)
ext {
set('snippetsDir', file("build/generated-snippets"))
}
// (3)
configurations {
asciidoctorExtensions
}
dependencies {
// (4)
testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
// (5)
asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
...
...
}
// (6)
tasks.named('test') {
outputs.dir snippetsDir
useJUnitPlatform()
}
// (7)
tasks.named('asciidoctor') {
configurations "asciidoctorExtensions"
inputs.dir snippetsDir
dependsOn test
}
// (8)
task copyDocument(type: Copy) {
dependsOn asciidoctor // (8-1)
from file("${asciidoctor.outputDir}") // (8-2)
into file("src/main/resources/static/docs") // (8-3)
}
build {
dependsOn copyDocument // (9)
}
// (10)
bootJar {
dependsOn copyDocument // (10-1)
from ("${asciidoctor.outputDir}") { // (10-2)
into 'static/docs' // (10-3)
}
}
(1)에서는 .adoc
파일 확장자를 가지는 AsciiDoc 문서를 생성해주는 Asciidoctor를 사용하기 위한 플러그인을 추가한다.
(2)에서는 ext
변수의 set()
메서드를 이용해서 API 문서 스니핏이 생성될 경로를 지정한다.
(3)에서는 Asciidoctor에서 사용되는 의존 그룹을 지정한다. asciidoctor task가 실행되면 내부적으로 (3)에서 지정한 asciidoctorExtensions
라는 그룹을 지정한다.
(4)에서 'org.springframework.restdocs:spring-restdocs-mockmvc'를 추가함으로써 spring-restdocs-core와 spring-restdocs-mockmvc 의존 라이브러리가 추가된다.
(5)에서 spring-restdocs-asciidoctor 의존 라이브러리를 추가한다. (3)에서 지정한 asciidoctorExtensions
그룹에 의존 라이브러리가 포함된다.
(6)에서는 test task 실행 시, API 문서 생성 스니핏 디렉토리 경로를 설정한다.
(7)에서는 asciidoctor task 실행 시, Asciidoctor 기능을 사용하기 위해 asciidoctor task에 asciidoctorExtensions
을 설정한다.
(8)은 build task 실행 전에 실행되는 task로, copyDocument task가 수행되면 index.html 파일이 src/main/resources/static/docs
에 copy되며, copy된 index.html 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용할 수 있다.
build/docs/asciidoc/
" 경로에 생성되는 index.html을 copy한다.src/main/resources/static/docs
" 경로로 copy된 index.html을 추가해준다.(9)에서는 build task가 실행되지 전에 copyDocument task가 먼저 수행되도록 한다.
(10)에서는 애플리케이션 실행 파일이 생성하는 bootJar task 설정이다.
http://localhost:8080/docs/index.html
) 후, API 문서를 확인할 수 있다.build.gradle에 API 문서 생성을 위한 설정이 완료되었다면, 마지막으로 API 문서 스니핏이 생성 되었을 때, 이 스니핏을 사용해서 최종 API 문서로 만들어주는 템플릿 문서(index.adoc
)를 생성해야 한다.
src/docs/asciidoc/
src/docs/asciidoc/
디렉토리 내에 비어있는 템플릿 문서(index.adoc
)를 생성해주어야 한다.해당 사전 준비가 완료되면, 테스트 케이스에 API 스펙 정보를 추가해주면 API 문서 스니핏을 생성할 수 있다.