백엔드 개발자

2 분 소요

서론

Doore 프로젝트는 과거 진행했던 KEEPER R2 프로젝트와 똑같이 Rest Docs를 사용하고 있습니다. Rest Docs를 선택한 이유는 테스트 코드 강제화와 팀원의 Rest Docs 학습 곡선이 없었기 때문입니다. Doore 프로젝트에서 모든 코드는 테스트 되어야 한다는 공통된 의견이 있었고, 다들 Rest Docs를 사용해 봤기 때문에 크게 부담이 없었습니다.

프론트 분들이 백엔드에서 만든 API 스펙을 알아야 작업이 원활하시기 때문에 배포서 버에서 API 문서를 확인할 수 있도록 했지만, 이상하게 API 문서가 개발 서버에 배포되지 않았습니다. 아래에서는 로컬 환경에서만 Rest Docs가 보였던 문제의 원인과 해결 방법, 빌드를 두 번 해야 문서가 보이는 문제를 해결하는 방법에 대해서 알아보도록 하겠습니다.

로컬에서만 RestDocs 문서가 보이는 문제 해결 방법

build 과정 중 하나인 bootJar task에서 asciidoctor 파일을 “static/docs” 파일 안에 복사하도록 하고 Gradle build를 두 번 해서 해결했습니다.

원래 코드에서는 “src/main/resources/static/docs”에만 asciidoctor 결과 파일을 복사했기 때문에 로컬 환경에서만 API 문서가 보였고 배포 서버에서는 확인할 수 없었습니다. bootJar task를 수정한 후 서버에 API 문서가 보일 것이라 기대했지만, 이전과 마찬가지로 개발 서버에서 API 문서를 확인할 수 없었습니다. Gradle Build 과정이 끝난 결과물의 파일을 뒤져 봤을 때 static 파일이 제대로 들어가 있었지만, 이상하게 배포가 되지 않았습니다. 로컬에서 빌드된 결과물은 static 파일이 제대로 들어 있었지만, EC2에서 빌드된 결과물을 가져왔을 때는 static 파일이 비어 있었습니다. GITHUB Action에서 빌드를 하고 결과물을 S3에 저장하는데 이 과정에서 무언가가 잘못되고 있다는 것은 알았지만 직접적으로 확인할 수 있는 방법이 없었습니다.

하룻밤을 지내고, 한 블로그 글에서 Gradle Build 과정을 두 번 해야 배포가 됐다는 글을 보고 CI/CD 과정 중 빌드를 한 번 더 하도록 수정했습니다. 자동 배포를 완료하고 개발 서버에 들어가 보니 성공적으로 API 문서가 배포되는 것을 확인했습니다.

RestDocs 이미지

해당 ISSUE와 PR은 Feature/#28-개발 서버에 Rest Docs가 배포가 안되는 문제 해결에서 확인하실 수 있습니다.

빌드를 두 번 해야 문서가 보이는 문제 해결

프론트 분들이 API 문서를 볼 수 있어야 원할한 작업을 할 수 있기 때문에 급하지만, Gradle Build를 두 번 해서 개발 서버에 API 문서를 배포했습니다. 자동화 배포가 조금 안정화되고, CICD 고도화를 진행하고 있어 이번 기회에 빌드를 두 번 해야 API 문서가 배포되는 문제를 해결하기로 마음먹었습니다. 저번에 모든 블로그를 뒤져봐서 안 됐기 때문에 과거 KEEPER 인프라를 담당하셨던 톰 선배님께 연락을 드렸습니다.

선배님께서도 똑같은 문제를 겪으셨는데 미니언 선배님께서 과거 Gradle 설정을 건드셔서 해결했다고 말씀해 주셨습니다. 과거의 KEEPER R2 PR을 모두 뒤졌을 때 Gradle 관련한 PR은 단 두 개였습니다. Doore 프로젝트와 다른 점은 아래와 같습니다.


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

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

분명 Spring Rest Docs 공식 문서에는 “/html5”를 넣으라고 되어있었지만, Keeper R2 프로젝트에서는 “/html5”를 삭제했습니다. 반신반의하며 수정 후 자동 배포를 진행했더니 귀신같이 API 문서 배포가 성공되었습니다. 그 후 문제의 원인에 대해서 조사했지만, 아직까지 원인은 찾지 못했습니다.

해당 ISSUE와 PR은 Feature/#37-rest_docs_배포_문제_해결 #70에서 확인하실 수 있습니다.

결론

로컬 환경에서만 API 문서가 보였던 문제는 JAR 파일 내부에 static 파일을 넣어주는 과정이 없었기 때문입니다. 빌드를 두 번 해야 API 문서가 보이는 문제의 원인은 아직까지 잘 모르겠으나 asciidoctor 결과가 나오는 경로를 재설정 함으로써 해결할 수 있었습니다.

카테고리:

업데이트:

참고