??? : 어딜 보시는 거죠 그건 제 잔상입니다만?!?

반응형

배경

진행 중인 프로젝트에서 API 문서화를 위해 Spring Rest Docs를 사용하고 있다

API 문서를 만드는 과정에서 생긴 html 파일을 함께 서버에 배포를 해서 사용을 하고 있고 https://{백엔드 도메인 주소}/docs/index.html 로 접속을 하면 문서가 나오도록 설정을 해두었고 이를 위해 build.gradle에 copyDocument 라는 Task를 만들어 두었다

tasks.register('copyDocument', Copy) {
    dependsOn asciidoctor
    doFirst {
        delete file('src/main/resources/static/docs')
    }
    from file("build/docs/asciidoc")
    into file("src/main/resources/static/docs")
}

순서로는 test → asciidoctor가 문서 생성 → src/main/resources/static/docs 하위에 html 문서 복사 → Spring boot 띄워서 https://{백엔드 도메인 주소}/docs/index.html 에서 문서 보여주기인데 API 문서가 나오지 않는 문제가 있었다

문제점

1. 혹시나 서버에 빌드, 배포 과정에서 문제가 있는 것은 아닐까 Intellij에서 run을 시키면 잘 나온다
   
   

2. 로컬에서 API 문서에 관련 된 것들을 모두 지우고 clean → build를 실행한 후 해당 jar 파일을 실행 시키면 나오지 않는다

뭐지 잔상인가….

 

320x100

가설

• resources/static 하위로는 잘 복사가 되지만 build 시점에 같이 패키징 되지 않는다

해당 가설을 확인하기 위해 jar -tf를 통해서 패키징 된 내부 파일들을 확인 해 봤는데 역시나 index.html 파일이 확인되지 않았다

해결 방법

현재 build 순서를 확인하면 test → asciidoctor → copyDocument → build 순서로 진행이 된다

여기서 문제는 test 이전에 processResources작업을 진행한다는 것이다

processResources 작업은 resource 파일을 클래스 디렉토리로 복사를 하게 되는데 해당 시점에는 API 문서가 복사가 되기 이전 시점이라 jar 파일에 들어가지 않는 것이다

해당 문제는 Spring Rest Docs 공식문서를 보면 해결이 되는데 다음과 같이 bootJar 시점에 직접 static/docs 밑으로 파일을 넣어주면 된다

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

추가로 기존에는 build 작업을 진행하던 것을 bootJar로 변경을 해주었다

참고

Spring REST Docs

Spring REST Docs

ProcessResources - Gradle DSL Version 8.4

ProcessResources - Gradle DSL Version 8.4