build 할 때 Rest Docs 파일이 생성이 안되는 문제 트러블 슈팅

build 할 때 RestDocs 파일이 생성이 안되는 문제 트러블 슈팅

0. 들어가기 전에

저희 프로젝트는 RESTDocs를 파일을 만들어서 API를 문서화를 했습니다. 각각의 API를 종류에 맞게 adoc 파일로 관리를 해 유지보수를 하기 쉽게 사용하고 있었습니다. 하지만 이 방식의 단점은 한눈에 어떤 종류의 API가 있는지 파악하기가 어려웠습니다. 그래서 만들어진 adoc 파일을 하나의 파일로 만들 수 있는 gradle task를 만들어 사용했습니다(참고 PR). 하지만 이 과정에서 문제가 발생했는데, 이 글은 그 문제를 어떻게 해결했는지에 대해서 설명하는 글입니다.

1. 문제 상황

먼저 intellij에서 spring boot를 실행시키면 gradle에 작성한 task 대로 정상 작동합니다.

tasks.named('asciidoctor') {
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'
    sources {
        include("**/index.adoc")
    }
    baseDirFollowsSourceFile()
    dependsOn test
}

asciidoctor.doFirst {
    delete file('src/main/resources/static/docs')
}

task copyDocument(type: Copy) {
    dependsOn asciidoctor
    from file('build/docs/asciidoc')
    into file('src/main/resources/static/docs')
}

build {
    dependsOn copyDocument
}

깔끔하게 생성되고, http://localhost:8080/docs/index.html에서도 정상 접근이 가능합니다.

하지만 개발 서버로 배포하고 문제가 생겼는데요.

바로 404 에러가 발생합니다.

이걸 보면서 원인을 두 가지로 생각했습니다.

1. nginx가 접근을 막았다.
2. index.html이 없다.

1번 같은 경우는 다음과 같이 nginx access.log에 찍혀있기 때문에 원인이 아니었습니다.


그럼 2번이 확실하니 로컬에서 한 번 직접 명령어를 쳐서 확인해 보겠습니다.

./gradlew build
jar -tf ${jar이름}.jar # -tf 빌드된 파일의 내부 파일을 확인해 볼 수 있는 명령어입니다.

index.html이 jar에 없는 게 확인되었습니다. gradle를 직접 실행하면 intellij로 실행할 때와 다르게 무언가 다르게 동작하는 것 같습니다.

2. 해결 과정

그렇다면 gradle를 할 때 로그를 보겠습니다. 저희는 실제로 github actions를 통해 gradle를 하고 있으니, actions의 log를 확인해 보겠습니다.

Task 순서는 다음과 같은데요. asciidoctor와 copyDocument는 아래 로그에 정상적으로 동작하는 것을 확인했습니다.

자세히 보면 bootJar가 test 전에 위치하는걸 볼 수 있습니다.

저희는 aciidoctor의 task를 test -> asciidoctor -> copyDocument 로 해놓았기 때문에 adoc 파일이 생성되지 않은채로 jar 파일이 생성되었던 것이 원인이었습니다.

그래서 저는 gradle에 dependsOn 명령어를 추가해 주었습니다.

bootJar.dependsOn('copyDocument')

bootJar가 copyDocument에 의존하도록 하여 copyDocument라는 task가 끝난 후에 jar 파일이 실행되게 바꿨습니다.

성공하리라는 기대를 안고 빌드를 해봤지만, 빌드 파일에 index.html이 생기지 않았습니다. 삽질 끝에 원인을 알아냈는데요. 바로 processResources 때문입니다. gradle의 processResources은 resource에 있는 파일을 build 디렉토리도 복사합니다. 즉, index.html이 생성이 안 되었을 때, 복사해서 build 디렉토리로 붙여넣기 때문에 오류가 발생했다고 할 수 있습니다.

그래서 copyDocument를 할 때 직접 build 파일로 복사하도록 변경해 주었습니다.

task copyDocument(type: Copy) {
    dependsOn asciidoctor
  from file('build/docs/asciidoc')
    into file('build/resources/main/static/doc')
}

3. 결과

그 후 bootJar를 실행할 때 정상적으로 index.html이 포함돼 정상적으로 웹에서 접근이 가능하게 되었습니다.