restdoc이 static/doc/index.html url로 나오지 않는 문제

결론부터 말하자면, Maven Plugin 순서로 인해 일어난 문제였다.

 

문제

src/main/doc에 index.adoc이 있음에도, 

static/docs/index.html로 호출할 때, restDoc이 뜨지 않는 문제가 있었다.

문제 원인

처음에 url 경로 문제인 줄 알았으나, WebMvcConfig.java에서 /static/** 으로 시작하는 url은 classpath:/static/ 디렉토리에서 정적 리소스를 찾는 설정을 확인하였다. 

 

classpath:/static/ 경로는, 기본적으로 target/classes와 매핑된다.

참고로, target은 maven으로 프로젝트를 컴파일할 때 컴파일한 결과물로 만들어지고, 애플리케이션 동작하는 것은 target에 컴파일 된 소스들로 하게 된다.

즉, static/docs/index.html로 url을 호출하면 target/classes/static/docs/index.html 파일을 반환하게 된다.

 

근데, target/classes에 static 디렉토리가 존재하지 않았다.

프로젝트를 컴파일할 때 생긴 문제라 생각하고, maven으로 빌드했기 때문에 pom.xml을 확인하였다.

 

SpringBoot에서 애플리케이션을 실행시킬 때, pom.xml에 있는 spring-boot:run인 goal이 실행된다.

터미널에서 mvn spring-boot:run 메이븐 명령어로도 애플리케이션을 실행시킬 수 있다.

 

maven의 모든 작업은 pluigin에서 수행된다. <build> 아래 <plugins>에서 빌드할 때 수행되는 플러그인 목록대로 순차적으로 수행된다.

plugin 중 restdoc의 문서가 생성되는 /generated-docs에서 /static/docs로 복사해주는 execution을 발견하였다.

 

/generated-docs의 restdoc html 문서는 asciidoctor 플러그인에서 만들어 준다.

 

asciidoctor 플러그인은 /generated-docs를 /static/docs로 복사해주는 플러그인보다 더 아래에 있었다.

즉, plugin의 순서가 뒤바뀌었기 때문에, asciidoctor 플러그인이 /generated-docs에 restdoc html 문서를 생성하기 전에, html을 복사하는 플러그인이 실행된다는 것이다.

 

문제 해결

asciidoctor 플러그인을 파일을 복사하는 플러그인인 maven-resources-plugin보다 위에 명시해주었다.

 

static/docs에 restdoc html 파일들이 생성된 것을 확인할 수 있다.

 

다시, static/docs/index.html로 호출했을 때 html 문서가 나오는 것을 확인할 수 있다.

참고 자료

https://wikidocs.net/18341

05. Goal 정리

 

https://100100e.tistory.com/390

Maven에 대해서 알아보자