Spring REST Docs로 생성한 API 문서의 배포 문제를 해결한 과정

지난 Spring REST Docs 적용기에서 만들어 본 API 문서를 EC2 서버에 배포해봤다.

 

build.gradle 파일에 아래처럼 asciidoctor가 생성한 문서를 "static/docs" 경로로 이동시키는 명령어를 추가했다. 프로젝트의 resources/static 패키지에 들어있는 다른 파일들처럼 API 문서도 정적으로 호스팅되길 기대하면서..

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

 

하지만 호스팅되어 있어야 할 URL 주소는 내 문서를 띄워주지 않았다. 문서 파일이 생성된 후에 resources/static/docs 디렉토리로 이동시켰음에도 불구하고, API 문서만 접근할 수 없었다.

 

JAR 파일의 내용물을 확인할 수 있는 명령어를 알게 돼서, 터미널에 "jar tf"를 입력해 봤다. 다행히 HTML 문서가 제대로 생성됐고, static/docs 경로에 존재하긴 했다.

 

그런데 자세히 보니 API 문서는 말 그대로 static/docs 경로에 들어가 있고, 원래 resources/static 디렉토리에 있던 다른 파일들(JS, CSS 등)은 정작 다른 곳에 있었다..

 

"BOOT-INF/classes"로 시작하는 경로에 있어야 호스팅된 URL로 이동할 수 있었다. API 문서 파일들도 같은 곳에 들어가있어야 하지 않을까?

 

하여 기존에 "static/docs"로 설정해뒀던 경로를 "BOOT-INF/classes/static/docs"로 바꿔보았다.

bootJar {
    dependsOn asciidoctor
    from ("${asciidoctor.outputDir}") {
        into("BOOT-INF/classes/static/docs")
    }
}

 

그 결과 BOOT-INF/classes 경로에 함께 들어갔고, 문서에 제대로 접근할 수 있게 됐다!

 

 

+ 배포된 문서를 확인하는 도중, 컨텐츠에 "Unresolved directive in..." 워딩이 들어가 있는 것을 발견했다.

 

main.adoc에 다른 .adoc 파일의 내용물을 include:: 방식으로 연동해둔 것이 제대로 동작하지 않고 있었다.

 

이 문제는 build.gradle 내 asciidoctor 설정에 baseDirFollowsSourceDir()를 추가해 해결할 수 있었다. 다른 파일을 참조할 경우 동일한 소스의 경로에서 찾도록 한 것이다.

asciidoctor {
    baseDirFollowsSourceDir() // 추가
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'
    dependsOn test
}

 

 

이렇게 asciidoc 문서의 배포까지 완료해봤다. 실 프로젝트가 아니어서 API 문서 경로를 공개적으로 두었지만, 만약 실제로 서비스를 한다면 일반 사용자는 문서에 접근할 수 없도록 따로 조치가 필요할 것 같다.