[Spring REST Docs] 빌드 시 HTML 이 생성되지 않을 때

개요

프로젝트에서 Spring REST Docs 를 이용하여 API 문서를 만들었다.

빌드 시 adoc 파일을 바탕으로 HTML 파일을 생성하고 싶어 Spring REST Docs 공식 문서 (2.0.7.RELEASE 사용) 를 참고하였는데, 빌드를 하여도 HTML 파일이 생성되지 않는 문제가 발생했다.

결론부터 말하자면 adoc 파일을 바탕으로 빌드 시 생성되는 HTML 파일의 위치가 가 공식 문서에 나온 것과는 다른 것이 원인이었다.

 

원인

 

위의 공식 문서를 보면 src/docs/asciidoc 하위에 adoc 파일을 두었을 때, 그래들로 빌드 시 build/asciidoc/html5 하위에 html 이 생성된다.

 

 

이를 바탕으로 HTML 문서를 jar 에 패키징하려면 위와 같이 build.gradle 에 작성하면 된다. 코드는 ${asciidoctor.outputDir}/html5 에 있는 파일을 jar 패키징 전에 static/docs 에도 두도록 하는 스크립트이다. 여기서 ${asciidoctor.outputDir} 는 위에서 봤듯이 build/asciidoc 이다. 

그런데, 나는 빌드를 몇 번이고 clean 하고 다시 해도 static/docs 에 HTML 파일이 생성되지 않았다. 빌드 시에 adoc 을 바탕으로 생성되는 HTML 파일의 위치도 공식 문서와는 달랐다.

이걸 확인하고 난 후에 ${asciidoctor.outputDir} 아래와 같이 찍어보니,

bootJar {
    dependsOn asciidoctor
    println("start bootJar")
    println("${asciidoctor.outputDir}")
    copy {
        from("${asciidoctor.outputDir}")
        into 'src/main/resources/static/docs'
    }
}

${asciidoctor.outputDir} 가 공식문서와는 달랐다.

이를 확인하고 build.gradle 의 bootJar 코드를 아래와 같이 수정하니 정상적으로 HTML 파일이 static/docs 하위에 생성되었다.

bootJar {
    dependsOn asciidoctor
    copy {
        from("${asciidoctor.outputDir}")
        into 'src/main/resources/static/docs'
    }
}