Spring Rest docs 적용

dependencies {
    testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")
    asciidoctor("org.springframework.restdocs:spring-restdocs-asciidoctor") // restdocs asciidoctor의 extension을 사용하기 위한 의존성 추가
}

Rest docs를 사용하기 위해서는 위 의존성만 추가하면 된다.

하지만 .adoc 파일을 .html 파일로 바꾸어서 build된 파일의 특정 폴더(static)에 해당 파일 이동시키기 위해 plugin 설정이 필요한데 여기서 꽤 애를 먹었다.

우선 위와 같은 작업을 하기위해서는 asciidoctor.convert plugin이 필요하다.

plugins {
    id("org.asciidoctor.convert") version "1.5.9.2"
}

위와 같이 plugin을 추가해준다. 현재 3.x 버전이 최신버전이며 우아한형제들 기술블로그를 참고하여 1.5.9.2 버전을 사용했다.

Rest docs 기능을 클라이언트에게 제공하기 위해서는 빌드과정에 아래와 같은 과정이 필요하다.

1. snippet 생성
2. .adoc -> .html 변환
3. .html로 변환 된 파일을 static 폴더로 이동(복사)

gradle의 task에 설정해주어 위 과정을 진행한다.

대부분의 예제 코드에서 3번 과정을 BootJar task에서 진행하였는데 몇번을 빌드하여도 .html 파일이 생성은되나 원하는 폴더에 복사가 되지는 않았다.

    tasks.withType<org.asciidoctor.gradle.AsciidoctorTask> {
      dependsOn(tasks.withType<Test>())
      doLast {
          copy {
              from("${asciidoctor.outputDir}/html5")
              into("$buildDir/resources/main/static/docs")
          }
      }
    }

    val asciidoctor = tasks.getByName("asciidoctor") as org.asciidoctor.gradle.AsciidoctorTask

    tasks.withType<org.springframework.boot.gradle.tasks.bundling.BootJar> {
        dependsOn(tasks.withType<org.asciidoctor.gradle.AsciidoctorTask>())
    }

위와 같이 복사하는 과정을 AsciidoctorTask로 이동하여서 해결하였다.
예상되는 이유는 여러가지 경우의수로 테스트해본 결과 build된 파일이 생성되기전에 복사를 시도하여 복사가 되지않는것으로 판단하였다.