[Rest Docs] Spring Boot API 문서 자동화 설정

목차

 

1. REST Docs란?

REST API 문서 자동화 도구이다. 테스트 코드 기반으로 Docs를 고려해서 작성하면 자동으로 API문서를 작성해준다. 테스트 코드 기반이기 때문에 필수로 작성해야하며 테스트 코드에 이슈가 발생하면 빌드가 실패하여 문서가 작성되지 않는다.

 

2. REST Docs 환경 세팅

build.gradle 파일을 아래와 같이 작성한 후 reload하여 다운 받는다.

(1) build.gradle 파일 내용

plugins {
    id 'java'
    id 'org.springframework.boot' version '2.7.4'
    id 'io.spring.dependency-management' version '1.1.0'
(+) id "org.asciidoctor.jvm.convert" version "3.3.2"
}
 
group = 'com.example'
version = '0.0.1-SNAPSHOT'
 
java {
    sourceCompatibility = '8'
}
 
configurations {
(+) asciidoctorExtensions // dependencies -> asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
 
    compileOnly {
        extendsFrom annotationProcessor
    }
}
 
repositories {
    mavenCentral()
}
 
dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
 
    implementation group: 'com.github.gavlyukovskiy', name: 'p6spy-spring-boot-starter', version: '1.8.0'
    implementation("p6spy:p6spy:3.9.1")
 
    compileOnly 'org.projectlombok:lombok'
    developmentOnly 'org.springframework.boot:spring-boot-devtools'
    runtimeOnly 'org.postgresql:postgresql'
    annotationProcessor 'org.projectlombok:lombok'
(+) asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
 
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
(+) testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc' // 문서 작성에 필요한 테스트 코드 라이브러리
}
 
(+) ext {
(+)     snippetsDir = file('build/generated-snippets') // 테스트 코드 실행 시 해당 경로로 스니펫 생성
(+) }
 
tasks.named('test') {
(+) outputs.dir snippetsDir // 위에서 정의한 경로 설정
    useJUnitPlatform()
}
 
(+) asciidoctor {
(+)    dependsOn test
(+)    configurations 'asciidoctorExtensions'
(+)    inputs.dir snippetsDir
 
(+)    sources{
(+)        include("**/index.adoc","**/common/*.adoc") // 생성할 index.html에 adoc 가이드 문서 코드 포함
(+)    }
(+) }
 
(+) asciidoctor.doFirst {
(+)     delete file('src/main/resources/static/docs') // 해당 경로에 파일 초기화
(+) }
 
(+) task copyDocument(type: Copy) {
(+)     dependsOn asciidoctor
        // build와 프로젝트 경로에 index.html 생성
(+)     from file("build/docs/asciidoc")
(+)     into file("src/main/resources/static/docs")
(+) }
 
(+) build {
(+)     dependsOn copyDocument
(+) }
 
bootJar {
    archiveBaseName = 'energy-tech'
    archiveFileName = 'backend.jar'
    archiveVersion = '0.0.1'
 
(+)     dependsOn asciidoctor
(+)     from ("${asciidoctor.outputDir}/html5") {
(+)         into 'static/docs' // resources/docs 경로에 index.html 생성
(+)     }
}
 
 

 

(2) index.adoc 파일 내용

 - src/docs/asciidoc 경로에 index.adoc 파일을 생성하여 디폴트 가이드를 작성한다.

= Spring REST Docs 작성 가이드
:doctype: book
:icons: font
:source-highlighter: coderay
:toc: left
:toc-title: 목차
:toclevels: 3
:sectlinks:
:sectnums:
 
== [내용을 작성하세요]
-[내용을 작성하세요]
 
 [내용을 작성하세요]
 
- [내용을 작성하세요]
 

(3) 테스트 코드 작성 및 실행하여 스니펫 생성

꼭 'All Tests'로 실행해야 스니펫이 생성된다.

(4) gradle 전체  빌드

빌드를 실행하여 실행에 필요한 파일들을 생성한다.

$ ./gradlew clean build

다음은 실행에 필요한 파일이다.

• build/docs/asciidoc/index.html
• build/generated-snippets/*/*.adoc
• build/libs/backend.jar
• src/main/resources/docs/index.html

 

3. Spring REST docs 실행 및 적용 확인

@SpringBootApplication 실행한 후 http://localhost:8080/docs/index.html 으로 접근하여 문서를 확인한다.