필자는 백기선님의 '스프링 기반 REST API 개발' 강의를 들으면서 실습을 진행하던 중에 문제가 발생하였고 실습과 동일하게 설정하는 방법에 대해 기록한 내용입니다.
문제 발생 원인
실제 인프런 강의는 Maven Build Tool 환경에서 진행했으나, 필자는 철저한 Gradle 파이기 때문에, Gradle로 실습을 진행하였습니다. 문제는 Spring REST Docs 문서를 빌드할 때 발생했습니다. Maven의 경우 플러그인 설정을 추가하고 Spring REST Docs 공식 레퍼런스에 따라서 설정을 진행하고 IntelliJ IDE의 Build Tool 메뉴에서 package를 더블클릭하면, 설정했던 plugin들에 의해서 test에 설정했던 snippsets 들을 생성하여 문서를 만들고 문서를 SpringBoot가 기본적으로 지원하는 static directory에 들어가서 우리가 앱 서버를 띄우면 API 문서 페이지를 바로 View에서 확인할 수가 있다.
문서는 target 폴더에 generated-docs 폴더 아래에 index.html(Spring REST Docs 이름을 index.html으로 설정했다고 가정) 파일이 생성되는 것을 확인할 수 있다.
그와 더불어 아래와 같이 target/static/docs 폴더 아래에도 index.html이 생성된 것을 확인할 수 있다.
이렇게 생성이 된 것을 확인했으면, 웹 서버를 띄우고 URI에 docs/index.html을 입력하면, Spring REST Docs를 조회할 수 있다!
하지만 문제점은 Gradle로 Spring REST Docs을 사용하기 위한 설정을 하게 되면(레퍼런스 동일) target 폴더에 snippsets이라던지 docs가 생성되는 Maven과는 달리 아래와 같이 build directory에 snippsets와 docs가 생성된다.
예상했을지 모르겠지만, 이 docs의 생성경로가 Maven과 달라서인지, 웹 서버를 실행하여 uri에 doc/index.html을 입력해도 Spring REST Docs를 조회할 수 없다. 이런 경우에 웹 서버를 통해서 생성한 Spring REST Docs를 조회할 수 있도록 하려면 어떻게 해야할까? 이 방법이 최선인지는 확실치 않지만, 방법이 하나 있다. 간략히 설명하면 build에 생성된 Spring REST Docs 문서를 static/doc 경로에 복사해주면 된다. 단순히 build.gradle에 아래의 코드를 추가하면 된다.
task copyDocument(type: Copy) {
dependsOn asciidoctor
from file("build/asciidoc/html5/")
into file("src/main/resources/static/doc")
}
build {
dependsOn copyDocument
}그 후 build를 실행하면 아래와 같이 static/doc 폴더에 index.html 파일이 복사된 것을 알 수 있다.
그 이후 uri에 doc/index.html을 입력하면
정상적으로 Spring REST Docs를 조회할 수 있다!
출처: API 문서 자동화 - Spring REST Docs 팔아보겠습니다
출처: Spring기반 REST API 개발 - 백기선님