Restdocs 빌드파일 위치 못찾는 에러, Unresolved directive in

Restdocs로 문서를 만들고 베타 배포를 했는데, 배포만 하면 귀신같이 아래와 같은 에러가 문서를 뒤덮었다.

Unresolved directive in test.adoc - include::{snippets}/api-controller-rest-docs-test/test_채널_변경_불가/response-fields.adoc[]
...

실제론 jenkins/~~ 로 시작하는 경로를 못 찾는다고 나와 있었다. local에서는 html문서도 잘 만들고 api 스펙도 잘 나왔는데 배포만 하면 안 나오니 삽질 시간이 길어졌다.

결국 답답해서 에러가 난 경로를 뚫어지게 쳐다보다가 그 원인을 파악할 수 있었다.

내가 만든 테스트 메소드 명은 아래와 같은 형태였다.

void TEST_채널_변경_불가() {
    ...
}

그리고 asciidoctor를 실행하면 아래와 같은 build.gradle 설정에 의해

ext {
    snippetsDir = file("$buildDir/generated-snippets")
}

generated-snippets 폴더 아래에 generated-snippets/테스트 클래스명/테스트 메소드명/adoc 파일
형태로 빌드가 되는데 이때 테스트 메소드 명이 전부 소문자로 변환돼서 폴더 생성이 되었다. 실제 테스트 메소드 명은 전부 대문자이다.

• 실제 테스트 메소드 명: TEST_채널_변경_불가
• 빌드된 폴더명: test_채널_변경_불가

아래와 같이 빌드됐다.

generated-snippets/api-controller-rest-docs-test/response-fields.adoc[]

그래서 테스트 메소드 명을 그냥 전부 한글로 바꿔주니깐 베타 배포 시에도 문서가 잘 나왔다.

그런데 의문인 점은 몇 가지 있다.

1. 로컬에서도 폴더명이 소문자로 바뀌는데 문서가 잘나왔다.
2. 그런데도 2번 연속 재배포했음에도 Unresolved directive ~ 에러가 나왔다.
3. 2번 연속 재배포했음에도 Last Updated 시간이 바뀌지 않았었다.

결론적으론 그냥 테스트 명을 바꿈으로써 문서가 update 되고 에러가 해결됐을수도 있다. 다음에 확인해보자.

따라서 로컬에서는 문서가 잘 보이는데 배포 시엔 문서가 보이지 않는다면 다음부턴 아래와 같은 절차를 수행해보자.

1. 문서 맨 아래에 Version Last updated 시간이 변경이 반영된 시간인지 확인하자.
2. 몇 번을 재배포해도 문서가 update 되지 않는다면 테스트 명을 바꿔보자.
3. 그래도 안 되면 혹시 테스트 명에 영어를 대문자로 쓰진 않았나 확인해보자.