58일차: Spring Rest Docs 사용을 위한 build.gradle 설정

Spring Rest Docs 사용을 위해서는 build.gradle에 다음과 같은 설정을 추가해야한다.

버전이나 일부 내용은 사용 환경이나 개발 방향에 따라 변경될 수 있다.

// (1)
plugins { 
    id "org.asciidoctor.jvm.convert" version "3.3.2"
}

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

// (3) 
configurations {
    asciidoctorExtensions
}

// (4)
dependencies {
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'  // (4-1)
    asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor' // (4-2)
}

// (5)
tasks.named('test') {
    outputs.dir snippetsDir  // (5-1)
    useJUnitPlatform()  // (5-2)
}

// (6)
tasks.named('asciidoctor') {
    configurations "asciidoctorExtensions"  // (6-1)
    inputs.dir snippetsDir  // (6-2)
    dependsOn test  // (6-3)
}

// (7)
task copyDocument(type: Copy) {
    dependsOn asciidoctor            // (7-1)
    from file("${asciidoctor.outputDir}")   // (7-2)
    into file("src/main/resources/static/docs")   // (7-3)
}

// (8)
build {
    dependsOn copyDocument
}

// (9)
bootJar {
    dependsOn copyDocument    // (9-1)
    from ("${asciidoctor.outputDir}") {  // (9-2)
        into 'static/docs'     // (9-3)
	}
}

(1) : AsciiDoc 문서를  생성해주는 Asciidoctor를 사용하기 위한 플러그인을 추가한다.

      예전 블로그 자료를 보면 (org.asciidoctor.converter)를 사용한 내용들이 있는데,

      org.asciidoctor.converter는 JRuby로 작성된 변환 모듈이다.

      Gradle 6이상에서는 JRuby를 지원하지 않으므로 org.asciidoctor.jvm.convert 모듈을 사용한다.

(2) : 스니펫 디렉토리 설정

      Gradle의 프로젝트 확장 프로퍼티에 snippetsDir라는 이름의 값을 설정하고 API 문서 스니펫이 생성될 경로를 지정한다.

      ext { snippetsDir = file("build/generated-snippets") } 와 같은 역할을 한다. (타입, 문법적 차이)

(3) : 프로젝트에서 사용할 의존 그룹을 지정한다.

      Asciidoctor를 사용하는 프로젝트에서는 Asciidoctor의 기능을 확장하는 플러그인이나 확장 모듈을 사용할 수 있다.

      이런 확장 모듈을 사용하려면 해당 확장 모듈을 프로젝트 의존성으로 추가해줘야하는데,

      asciidoctorExtensions 구성을 사용하면 확장 모듈을 관리할 수 있다.

(4) : 의존성 추가

    (4-1) : Spring REST Docs에서 제공하는 MockMvc 테스트 지원 모듈 추가

      spring-restdocs-mockmvc는 spring-restdocs-core에 의존하므로 spring-restdocs-core도 의존 라이브러리로 추가된다.   
      spring-restdocs-core모듈은 Asciidoctor를 사용해 HTML문서를 생성하고 RESTful API의 요청과 응답에 대한

      문서화 작업을 수행한다.

      spring-boot-starter-test에 포함된 spring-test 모듈과 함께 사용하게되면 MockMvc를 통해 API 문서화를 자동화 하는 기능을

      제공한다.

    (4-2) : asciidoctorExtensions 의 확장 모듈 추가

      Asciidoctor를 사용해 문서를 생성할 때 사용되는 확장 모듈이다. 'include::' 구문을 사용해 스니펫을 문서화 할 수 있도록 지원한다.

(5) : Gradle의 "test" task에 대한 설정

      Gradle에서 task란 빌드 작업 단위를 말한다. 입력을 처리해서 출력을 생성하고 다른 task의 입력으로 다시 사용될수도 있다.

    (5-1) : 'outputs.dir snippetsDir'는 snippetsDir를 출력 디렉토리로 설정한다는 의미이다.

      테스트 실행중 생성되는 스니펫 파일이 이 디렉토리((2)에서 설정한 snippetsDir)에 저장된다.

    (5-2) : 'useJUnitPlatform()'은 JUnit 5 테스트 엔진을 사용한다는 의미이다.

      Spring Boot 2.x 버전부터 기본적으로 JUnit 5를 사용하므로 명시적으로 사용하도록 설정할 필요는 없다.

      (이전 버전의 Spring Boot를 사용하거나 JUnit 4를 사용하면 설정해주어야한다.)

(6) : Gradle의 "asciidoctor"  task에 대한 설정

    (6-1) : asciidoctorExtensions 의존성을 asciidoctor task에 적용시킨다.
      의존성을 설정해줌으로써 asciidoctor task를 실행하면  Asciidoctor 기능을 사용할 수 있게된다.

    (6-2) : snippetDir가 입력 디렉토리로 설정된다. Gradle이 asciidoctor task를 실행할때 이 디렉토리에 있는 파일이

      변경되어있는지 확인하고 변경되었다면 태스크를 다시 실행한다. 따라서 항상 최신의 스니펫 파일을 유지할 수 있다.

    (6-3) : asciidoctor task가 test task에 의존하도록 설정한다.

      test task가 먼저 실행되어 스니펫 파일이 생성되고 asciidoctor task에서 이 스니펫 파일을 참조한다.

(7) : copyDocument task 정의

      (5), (6)의 task는 tasks.name(task이름)을 통해 Gradle에서 이미 정의된 task 중 이름이 일치하는 것을 가져오는것이다.
      task copyDocument(type: Copy)는 새로운 task인 copyDocument를 생성하는것을 의미한다.

      Copy 타입의 task는 파일 또는 디렉토리를 복사하거나 이동하는 작업을 수행할 수 있는 task 타입이다.

    (7-1) : copyDocument가 asciidoctor task에 의존한다는 것이다. asciidoctor task가 끝난 후 실행된다.

    (7-2) : 어느 디렉토리에서 파일을 복사해올지 정의한다. ("build/docs/asciidoc")

    (7-3) : 복사된 파일을 어디에 저장할지 설정한다.

      최종적으로 Asciidoctor로 생성된 문서 파일들을 애플리케이션의 정적 리소스 디렉토리로 복사한다.

      이를 통해 애플리케이션을 실행할 때 해당 문서를 볼 수 있게 된다.

(8) : build task가 실행되기 전에 copyDocument task가 수행되도록 설정한다.

      Gradle에서 일부 task는 이름을 별도로 선언하지 않아도 사용 가능함. tasks.named("build")와 동일한 역할을 수행함

(9) : bootJar task를 구성한다.

      bootJar는 빌드된 애플리케이션을 실행 가능한 jar 파일로 패키징하는 작업을 수행한다.

      bootJar를 실행하면 실행 가능한 파일이 build/libs 디렉토리에 생성된다.

    (9-1) : bootJar task 실행전에 copyDocument task가 먼저 실행되도록 의존성을 설정한다.

      따라서 bootJar를 실행하면 copyDocument 가 먼저 실행되므로 생성된 jar 파일에는 asciidoctor로 생성된 문서가 포함된다.

    (9-2) : task의 소스 디렉토리를 설정한다. AsciiDocs로 작성된 문서 파일이 포함된다.

    (9-3) : asciidoctor.outputDir 디렉토리에 있는 파일을 "static/docs" 디렉토리에 포함시키도록 설정한다.

      최종적으로 bootJar가 생성하는 JAR 파일에 문서 파일이 포함된다.

+ API 문서 스니펫을 사용하기 위한 템플릿(source 파일) 생성

      위에서 build.gradle API 문서 생성을 위한 설정이 완료되었다.

      스니펫은 문서 조각이므로 API 스니펫을 사용해 최종 API 문서로 만들어주기 위해서는 템플릿 문서가 필요하다.

      Gradle 기반 프로젝트는 "src/docs/asciidoc/" 경로에 해당하는 디렉토리를 생성해주어야한다.

      마지막으로 "src/docs/asciidoc/" 경로에 템플릿 문서 "index.adoc"를 생성해주면 된다.

      모든 테스트 코드가 정상적으로 작성 및 passed되면 index.adoc에서 설정한 양식대로 src/main/resource/static/docs 경로에 index.html 파일이 생성된 것을 확인할 수 있다.

 

참고자료

API 문서 자동화: https://tecoble.techcourse.co.kr/post/2020-08-18-spring-rest-docs/

Spring Rest Docs 적용: https://techblog.woowahan.com/2597/ (Gradle 4, JUnit 4 버전. 비교용으로 참고)

Gradle 버전 변경 RestDocs 적용 트러블 슈팅: https://prolog.techcourse.co.kr/studylogs/2499

Spring rest docs 적용기: https://velog.io/@max9106/Spring-Spring-rest-docs를-이용한-문서화

---

이번 실습을 하면서 가장 복잡했던 부분이 build.gradle 파일에 설정을 추가하는 것이었다.

이때까지는 의존성 한줄만 추가하거나, 길어도 두세줄만 추가하면 돼서 크게 어려움이 없었는데

이번에는 너무 많은 부분이 추가돼서 막막하게 느껴졌었다.

그래도 코드별로 하나씩 역할과 작성 방법에 대해 알아보니 전체 흐름을 이해할 수 있었다.

게다가 구글링을 하다보니 버전에 따라서도 변경되는 내용이 꽤 많이 있었다. 이전 버전과 바뀐 부분을 비교하는 과정도 재밌게 느껴졌다.

처음 실습을 진행할때는 설정파일은 따라서 타이핑만 하는 수준으로 진행했는데 각 코드가 어떤 역할을 하는지 알고나니 task를 왜 수행하는지 혹은 왜 이 경로에 파일이 생성되는지 등 여러가지를 알 수 있어서 좋았다.

아무래도 하나씩 찾아보다보니 시간은 조금 걸렸지만 아깝지 않은 시간이었다. 연휴를 앞두고 기분좋은 시작이다 :)