Spring REST Docs 사용하기 - 설정

1. Spring REST Docs 사용하기 - 설정
2. Spring REST Docs 사용하기 - 테스트코드 작성과 adoc
3. Spring REST Docs 사용하기 - 커스텀

API 문서를 작성하는 일은 힘들고 귀찮은 일이다. 문서화 작업은 필요한 작업이라고 생각은 되지만 역시나 귀찮은건 똑같다. 그래서 최대한 코드로 작성을하고 자동화를 통해 문서를 생성하는 방법중에 보통 Swagger를 사용했던것 같다. 하지만 이마저도 코드상에 덕지덕지 붙는 어노테이션들을 보자하니 더더욱 복잡해 지는것 같아 예전에 들었던 REST Docs이 생각났다.

 

이번 프로젝트에 REST Docs을 사용할 예정이기에 설정부터 차근차근 기록으로 남겨두기 위해 글을 작성한다.

 

Spring REST Docs

스프링 REST Docs 공식문서

Spring REST Docs

AsciiDoctor를 사용하고 이를 통해 HTML 문서를 뽑는다. Asciidoctor는 Controller Test(with MockMvc, WebClient, REST Assured)를 사용하여 *.adoc 확장자를 생성한다. 우리는 컨트롤러 테스트를 잘 작성하기만하면 알아서(적절한 간섭은 있겠지만) API 문서를 뽑아낼 수 있다.

 

설정

공식문서에서는 아래와 같이 Gradle의 build.gralde을 작성하라고 나와있다.

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

configurations {
	asciidoctorExt 
}

dependencies {
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' 
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' 
}

ext { 
	snippetsDir = file('build/generated-snippets')
}

test { 
	outputs.dir snippetsDir
}

asciidoctor { 
	inputs.dir snippetsDir 
	configurations 'asciidoctorExt' 
	dependsOn test 
}

우리 프로젝트는 Kotlin DSL을 사용하기 때문에 build.gradle을 아래와 같이 작성해 주었다

plugins {
    id("org.asciidoctor.jvm.convert") version "3.3.2"
}

val asciidoctorExt: Configuration by configurations.creating

dependencies {
    ...
    testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")
    asciidoctorExt("org.springframework.restdocs:spring-restdocs-asciidoctor")
}

tasks {
    // 1
    val snippetsDir = file("build/generated-snippets")
    
    // 2
    test {    
        outputs.dir(snippetsDir)
        useJUnitPlatform()
    }

    // 3
    asciidoctor {
        configurations(asciidoctorExtensions.name)
        // 4
        inputs.dir(snippetsDir)

        // 5
        forkOptions {
            jvmArgs("--add-opens", "java.base/sun.nio.ch=ALL-UNNAMED", "--add-opens", "java.base/java.io=ALL-UNNAMED")
        }
        
        // 6
        dependsOn(test)        
    }
}

1. asciidoctor에서 사용할 디렉토리를 정의한다

2. Test Task에서 사용할 출력 디렉토리를 설정한다

3. asciidoctor Task에 대한 설정이다

4. asciidoctor Task의 Input 디렉토리를 설정한다

5. 간혹 Warning이 표시될때가 있는데 그때 이 부분을 추가해주면 된다.

6. asciidoctor Task는 test Task 이후에 실행된다

 

이정도까지 왔다면 이미 반정도 끝난거 같다. 다음은 컨트롤러 테스트 코드를 작성하고 adoc파일이 만들어지는것과 adco파일을 어떻게 HTML로 변경할 수 있는지 알아보도록 하자