우당탕 Spring Rest Docs를 세팅기

문서화

지금 난 개인 프로젝트를 진행하고 있는데, 여지껏 웬만한 팀플 웹 과제에서는 문서화를 하다보니 문서화하는 게 익숙해졌다.
한 API가 어떤 것을 Request에 담아 어떤 방식으로 전달되어 어떤 내용들을 어떤 방식으로 Response해줄지를 시각화해주는 게 필요하다. 이래야 프론트엔드와 백엔드 사이의 한눈에 들어온다.

Swagger VS Rest Docs

처음에는 익숙한 스웨거를 쓸 생각이었다. 그런데 “spring boot 문서화”라고 검색해보니 rest docs가 있다는 것을 알았고, 그 둘을 비교한 글을 읽었는데 내 선택에 영향을 미친 중요한 내용이 있었다.
바로 rest docs는 테스트를 통과해야만 API 문서가 정의된다는 것이다. 난 혼자 프로젝트를 진행하지만, 개인적으로 테스트는 강제하고 싶었던지라 rest docs를 사용하기로 했다.

잘… 안 되네?

1. build.gradle 세팅

처음에는 공식 문서를 따라 했었다. 그런데 어김없이 뜨는 deprecated… 또는 버전이 너무 낮다는 경고.
경고와 deprecated를 전부 없앴더니 이번에는 asciidoctor가 테스트 후 adoc 파일을 만들지 않았다. 이건 추후 보니 테스트 결과 파일이 저장되는 경로의 문제였다.

나는 구글링으로 가장 최신의 글을 찾아서 따라했는데, 역시나 deprecated된 부분이 조금 있어서 여러 글들의 코드를 짜깁기하면서 계속 빌드를 해봤다. 그 과정에서 build.gradle에 세팅한 내용이 어떤 원리로 동작하는지 깨달았다.

configurations {
    asciidoctorExt
}

ext {
    set('snippetsDir', file("build/generated-snippets"))
}

dependencies {
    ...
}

tasks.named('test') {
    outputs.dir snippetsDir
    useJUnitPlatform()
}

asciidoctor {
    inputs.dir snippetsDir
    dependsOn test
}

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

bootJar {
    dependsOn asciidoctor
    copy {
        from "${asciidoctor.outputDir}"
        into "BOOT-INF/classes/static/docs"
    }
}

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

build {
    dependsOn copyDocs
}

여타 다른 부분은 제외하고 필요한 부분만 가져왔는데, 간단히 정리하면

1. 빌드를 할 때, copyDocs라는 작업이 실행
2. copyDocs는 asciidoctor라는 작업이 실행
3. asciidoctor는 기존 docs 파일을 삭제, snippetsDir을 이용하여 test 작업을 실행
4. test작업에서는 JUnit 테스트를 진행한 후, 결과물을 snippetsDir에 저장
5. build/docs/asciidoc에 있는 파일들을 docs 폴더 내로 이동 의 원리로 동작한다.

jar 파일을 만들 때에도 기본적인 원리는 같고, 파일이 저장되는 위치만 다르다.

2. adoc 파일 경로와의 싸움

내가 원한 그림은 로그인 카테고리 하위에 스팀 로그인, 로그아웃이라는 API를 위치시키는 것이었다.
그러기 위해서는 login이라는 adoc 파일과 하위의 steamLogin.adoc, logout.adoc이 있으면 되겠지 싶었다.

그랬더니 어찌된 영문인지 login.adoc에 steamLogin.adoc 경로를 지정해줬음에도 전혀 그 파일을 못 찾고 있었다.
그래서 설마 싶어 login.adoc 디렉토리를 기준으로 상대경로를 지정해줬더니 찾긴 찾는데, snippets이란 변수에 지정해둔 테스트 파일 경로를 못 찾았다.

결국 타협점을 찾은 게, 모든 API의 카테고리를 다루는 index.adoc을 만들어 같은 레벨의 폴더 내에 steamLogin.adoc및 다른 adoc 파일을 두고 해당 adoc 파일 내에서 snippets 경로를 지정하기로 했다.