처음에 Spring Rest Docs 설정해볼 때 생각보다 뭔가 쉽게 되지 않았었습니다.
블로그들을 참고해서 설정을 했더니 잘못된 정보들도 많이 있었는지 설정을 하고 난 후에도 만족스럽지 않은 부분이 있었고, 공식문서를 참고해서 제대로된 설정을 완료할 수 있었습니다.
삽질한 부분과 완료한 설정을 기록하려 합니다.

본 설정은 Spring 2.7.6 버전과 gradle 사용하였습니다.

전체 코드를 github 에서 확인할 수 있습니다.

HTML이 잔뜩 생기는 문제

처음에 저는 블로그들을 참고해서 Spring Rest Docs 설정을 해왔었습니다. 작동은 정상적으로 이루어 졌지만 마음에 안 드는 부분이 있었습니다. 그것은 생성된 문서의 HTML 파일이 git 에 포함되는 것이었습니다. 제가 참고한 코드들은 보통 생성된 HTML 파일을 src/main/resources/static/docs 로 이동시켰고 그래서 HTML 이 git에 포함된 것입니다.

위 이미지는 제가 했던 프로젝트 중 하나의 github 코드 비율인데 HTML 이 훨씬 더 많게 나오는 것을 볼 수 있습니다.
저는 뭔가 설정이 잘못되었다고 생각하고 공식 문서를 참고했습니다.

Spring Rest Docs 제대로 설정하기

설정한 build.gradle 파일을 보면서 설명하겠습니다.

plugins {
    id 'java'
    id 'org.springframework.boot' version '2.7.6'
    id 'io.spring.dependency-management' version '1.0.15.RELEASE'
    id 'org.asciidoctor.jvm.convert' version '3.3.2'    // 1
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'

repositories {
    mavenCentral()
}

configurations {
    asciidoctorExt // 2
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

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

test {
    outputs.dir snippetsDir	// 4
    useJUnitPlatform()
}

asciidoctor {	// 5
    inputs.dir snippetsDir	// 6
    configurations 'asciidoctorExt'	// 7
    dependsOn test	// 8
}

bootJar {
    dependsOn asciidoctor	// 9
    from ("${asciidoctor.outputDir}") {	// 10
        into 'static/docs'
    }
}

특히 볼드체로 되어있는 부분은 Spring initializer 를 사용하셔도 자동으로 해주지 않는 부분이므로 신경써주셔야 합니다.

1. Asciidoctor plugin 적용
   • Spring initializer 를 통해서 프로젝트를 생성하면 'org.asciidoctor.convert' 로 되어있을 텐데 변경해줍니다
   • gradle 버전으로 인해 변경해야한다고 합니다.
2. asciidoctorExt 를 설정
   • Asciidoctor를 확장하는 의존성을 위해 설정합니다.
   • Spring initializer 를 통해서 프로젝트를 생성하면 해당 부분이 없으므로 추가해줍니다.
3. Spring Rest Docs 를 통해 생성된 스니펫의 경로를 설정
4. test task 에 스니펫 디렉토리를 설정
5. asciidoctor task 설정
6. 스니펫 디렉토리를 input 디렉토리로 설정
7. asciidoctorExt 사용을 설정
8. 테스트가 실행된 후 실행되도록 설정
9. asciidoctor task가 실행된 후 실행되도록 설정
   • jar 를 생성하기 전에 문서가 먼저 생성되도록 하기 위함입니다.
   • Spring initializer 를 통해서 프로젝트를 생성하면 해당 부분이 없으므로 추가해줍니다.
10. 생성된 문서를 jar의 static/docs 디렉토리로 복사
    • Spring initializer 를 통해서 프로젝트를 생성하면 해당 부분이 없으므로 추가해줍니다.

이렇게 하면 git 에 HTML 문서를 포함시키지 않을 수 있습니다.

어플리케이션을 실행해도 문서가 안 보여요!?

그런데 위와 같이 설정하고 어플리케이션을 실행시켰는데 문서가 보이지 않았습니다.

혹시 아래와 같이 어플리케이션을 실행시키지 않았나요?

이렇게 실행을 하면 jar 를 실행시키는 것이 아닙니다. 하지만 저희는 HTML 문서를 jar 안에 넣었기 때문에 문서가 보이지 않을 것 입니다.

문서까지 포함한 어플리케이션을 실행하기 위해서는 gradle의 bootJar task를 통해서 jar 를 만들어주시고 이 jar를 실행시켜야 합니다.

bootJar로 jar를 만들어 주시고 아래와 같이 jar를 실행시키면

 java -jar build/libs/restdocs-setting-0.0.1-SNAPSHOT.jar

이렇게 문서가 정상적으로 보입니다.

참고

• https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/