REST Docs문서에서 스니펫이 불러와지지 않아요....

📌 문제 정의 & 원인 분석

지정된 경로에 HTML이 표시되지 않음

REST Docs 관련 코드를 배포한 후 /docs/index.html에 접속했지만 404 에러가 발생한다.
첫 번째로 의심되는 것은 index.html 파일이 CI/CD 과정 중에 누락되었을 가능성이다.

📌 해결 과정

step1

Asciidoctor를 통한 문서 생성 과정을 CI/CD 파이프라인에(ci-cd.yml) 명시적으로 추가한다. 이는 수동 문서 관리 시 발생할 수 있는 오류를 방지하고, 문서를 항상 최신 상태로 유지할 수 있게 돕는다.

- name: Create asciidoctor snippet
  run: ./gradlew clean asciidoctor
  shell: bash

step2

CI/CD 파이프라인에서 생성된 Asciidoctor 스니펫이나 기타 문서 관련 파일을 최종 애플리케이션 이미지로 복사하는 코드를 Dockerfile에 추가한다.

COPY --from=build /app/build/generated-snippets /app/generated-snippets

step3

API 문서를 애플리케이션과 같은 도메인에서 직접 접근 가능하도록 하기 위해, 스프링 부트에서 모든 요청을 정적 리소스로 처리할 수 있도록 설정한다.
application-develop.yml 파일에 모든 요청을 정적 리소스 요청으로 처리할 수 있는 설정을 추가했다.

static-path-pattern: "/**"

---

📌 문제 정의 2

스니펫이 텍스트로만 표시됨
할 수 있는 모든 조치를 끝내고 배포를 하니 '/docs/index.html' 접근은 성공했지만, 스니펫이 텍스트로만 표시된다.

📌 원인 분석

로컬의 index.adoc파일에서는 정상적으로 보였던 것을 미뤄보아 CI/CD 과정을 거치면서 스니펫 저장에 문제가 발생한 것 같다.

📌 해결 과정

git action에 들어가 Create asciidoctor snippet 부분의 로그를 보니 설정한 경로에서 스니펫을 찾을 수 없다는 로그가 나온다.

step1.

배포 서버의 /home/runner/work/build/generated-snippets/ 경로에 실제로 스니펫이 있는지 확인해야한다.
-> 확인 결과 해당 경로는 서버에 존재하지 않고, 도커 이미지 내에만 스니펫 파일들이 있는 것을 확인했다.

step2

도커 이미지에 있는 스니펫들을 서버에도 불러오기 위해 build.gradle에 스니펫을 포함하는 코드를 추가한다.

bootJar {
    dependsOn asciidoctor
    // asciidoctor 문서를 포함
    from("${asciidoctor.outputDir}") {
        into 'static/docs'
    }
    // generated snippets를 포함
    from("${project.buildDir}/generated-snippets") {
        into 'build/generated-snippets'
    }
}

dependsOn asciidoctor: 이 부분은 bootJar 태스크가 실행되기 전에 asciidoctor 태스크가 먼저 실행되어야 함을 지정한다.

from("${asciidoctor.outputDir}") { into 'static/docs' }: 이 구문은 Asciidoctor 태스크에 의해 생성된 정적 문서들을 asciidoctor.outputDir (Asciidoctor가 문서를 출력하는 디렉토리)에서 가져와, JAR 파일 내의 static/docs 디렉토리로 복사한다.

from("${project.buildDir}/generated-snippets") { into 'build/generated-snippets' }: 이 구문이 핵심이다. 프로젝트의 빌드 디렉토리 내에 생성된 API 스니펫들을 generated-snippets 폴더에서 가져와서 JAR 파일의 build/generated-snippets 경로로 복사한다.

이렇게 수정하고 배포하였다.

---

📌 문제 정의 3

큰일났다 이거 경로문제 아니다

수정 후 배포하였지만 이제는 서버의 /home/runner/work/build/generated-snippets/ 경로에 실제 스니펫 문서가 존재함에도 불구하고 문제가 지속된다.

📌 원인 분석

로컬 build.gradle의 asciidoctor 부분을 실행한 결과, git action 로그와 동일한 로그가 출력된다.
이는 CI/CD 파이프라인 문제가 아닌 코드의 문제라는 것이다...

그리고 착각한 부분이 있었는데, '/docs/index.html'의 경로에서 알 수 있듯이 로컬에서도 잘 동작하는지 알아보기 위해서는 index.adoc을 볼 것이 아니라 이 파일을 문서화한 index.html파일을 봐야했었다.

로컬에서 index.html 파일을 열어보니 서버와 똑같이 스니펫이 텍스트로 나온다. 그동안 로컬에서도 안되는 것을 로컬은 잘 돌아간다고 착각하여 삽질을 하고 있었던 것이였다!

💡 너무 허무한 해결

결국에는 의존성 문제였다.
REST Docs 초기설정을 하면서 관련 의존성 하나가 누락되었던 것이 원인이였다.

asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'

의존성을 추가하자 문제가 해결됐다🥲...

---

🫠 오늘의 교훈

의존성 확인좀 잘하자... 그런데 이쯤 되면 스프링에서 알아서 의존성 추가해주는 기능 만들어줘야 하는거 아니냐??