asciidoctor 를 통한 Spring REST Docs 자동 생성 세팅하기

Spring REST Docs 개요

RESTful 서비스의 문서 작성을 돕는다.

Spring MVC Test 와 함께 자동 생성된 스니펫과 Asciidoctor 로 쓰여진 수기 문서를 조합한다. Swagger 와 같은 도구에 의해 만들어진 문서화의 한계로부터 해방시켜준다.

정확하고, 간결하고, 잘 구조화된 문서를 생성하는 것을 돕는다. 이 문서화 방법은 사용자가 가장 쉬운 방법으로 정보에 접근할 수 있도록 돕는다.

Spring Boot Config

스프링 부트에서는 @AutoConfigureRestDocs 라는 애노테이션을 제공하여 테스트에 있는 Spring REST Docs 를 강화한다.

build.gradle 세팅 방법

plugins 세팅하기

plugins {
    // Asciidoctor
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
}

• Gradle 버전에 따라서 사용해야 하는 plugin 이 다르다.
  • Gradle 7 버전 이상의 경우는 org.asciidoctor.jvm.convert 를 사용하고, 3.3.2 버전을 사용하면 된다.
  • Gradle 7 버전 아래의 경우는 org.asciidoctor.convert 를 사용하고, 2.4.0 버전을 사용하면 된다.

dependencies 세팅하기

dependencies {
    // Spring REST Docs
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

• MockMvc 를 통한 테스트 코드로 문서를 생성하기 위해서 필요하다.

2.4.0 버전에는 asciidoc 의존성도 추가해주어야 한다.

ext 를 통해 외부 프로퍼티 설정하기

ext {
    snippetsDir = file('./build/generated-snippets')
}

asciidoctor task 의 의존성 세팅하기

asciidoctor {
    inputs.dir snippetsDir
    // 다른 Task 에 의존한다는 것을 알리는 것이다.
    // test Task 에 의존함을 알린다.
    // asciidoctor task 를 실행할 때, test task 를 먼저 실행한다.
    dependsOn test
}

• 주석에 자세한 설명이 있다.

test task 에서 할 일 늘리기

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

• output 을 snippetsDir 에 담도록 한다.

asciidoctor 실행 전에 할 일 세팅하기

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

• asciidoctor 를 실행하기 전, 해당 경로의 파일을 모두 지우도록 한다.

copyDocument task 생성하기

task copyDocument(type: Copy) {
    dependsOn asciidoctor
    from file("build/docs/asciidoc")
    into file("src/main/resources/static/docs")
}

• 만들어진 파일이 src/main/resources/statics/docs 에 위치하도록 한다.

build 에 의존성 걸기

build {
    dependsOn copyDocument
}

• build 시, copyDocument task 가 실행되어 문서를 위에서 정해진 위치에 복사하도록 한다.

풀세팅 참조

/*
 * This file was generated by the Gradle 'init' task.
 *
 * This generated file contains a sample Java application project to get you started.
 * For more details take a look at the 'Building Java & JVM projects' chapter in the Gradle
 * User Manual available at https://docs.gradle.org/7.4.1/userguide/building_java_projects.html
 */

plugins {
    // Apply the application plugin to add support for building a CLI application in Java.
    id 'application'

    // Spring boot plugins
    id 'org.springframework.boot' version '2.6.5'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'java'

    // Asciidoctor
    id 'org.asciidoctor.jvm.convert' version '3.3.2'
}

configurations {
    developmentOnly
    runtimeClassPath {
        extendsFrom developmentOnly
    }
}

repositories {
    // Use Maven Central for resolving dependencies.
    mavenCentral()
}

dependencies {
    ...
    // Spring REST Docs
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

application {
    // Define the main class for the application.
    mainClass = 'com.codesoom.demo.App'
}

javadoc {
    options.addStringOption("locale","ko_KR");
    options.addStringOption("encoding","UTF-8");
    options.addStringOption("charset","UTF-8");
    options.addStringOption("docencoding","UTF-8");
}

ext {
    snippetsDir = file('./build/generated-snippets')
}

test {
    useJUnitPlatform()
    outputs.dir snippetsDir
}

asciidoctor {
    inputs.dir snippetsDir
    // 다른 Task 에 의존한다는 것을 알리는 것이다.
    // test Task 에 의존함을 알린다.
    dependsOn test
}

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

task copyDocument(type: Copy) {
    dependsOn asciidoctor
    from file("build/docs/asciidoc")
    into file("src/main/resources/static/docs")
}

build {
    dependsOn copyDocument
}

문서 생성하기

테스트 코드를 이용하여 Asciidoc 문서 스니펫을 만들 수 있다.

@AutoConfigureRestDocs 애노테이션 붙이기

@SpringBootTest
@Utf8MockMvc
@AutoConfigureRestDocs
class ProductControllerTest {
  // ...
}

MockMvc 테스트의 메서드 체인에 andDo(document()) 메서드 추가하기

@Test
void list() throws Exception {
    // 목록을 이미 갖추고 있음
    mockMvc.perform(get("/products"))
            .andExpect(status().isOk())
            .andExpect(content().string(containsString("쥐돌이")))
            .andDo(document("get-products"));
}

• .andDo(document("get-products")) 부분이 REST DOCS 를 생성하는데 관여하는 코드이다.
• 해당 mockMvc 의 request 와 response 를 이용해 문서를 만들어준다.

test task 수행하기

./gradlew test

위 명령어를 입력하면, build/generated-snippets/get-products 폴더에 .adoc 확장자를 가진 Asciidoc 파일이 생긴다.

 

index.adoc 파일 만들기

src/docs/asciidoc/ 경로에 index.adoc 파일을 아래와 같이 생성한다.

ifndef::snippets[]
:snippets: ./build/generated-snippets
endif::[]

= API 문서

== `GET /products` - 제품 목록 얻기

HTTP request:

include::{snippets}/get-products/http-request.adoc[]

HTTP response:

include::{snippets}/get-products/http-response.adoc[]

• 사실 org.asciidoctor.convert 2.4.0 에서는 맨 위의 ... :snippets: ./build/generated-snippets ... 와 같은 부분을 명시하지 않아도 되는 것 같은데, 3.3.2 에서는 Unresolved ... 에러가 계속 나와서 명시해야 하는 것 같다.

asciidoc task 수행하기

./gradlew asciidoc

• 정석으로 하려면, test task 를 먼저 수행한 이후 build/generated-snippets/... 에 .adoc 문서가 만들어진것을 확인 후에 ./gradlew asciidoc 명령어를 수행해야 하지만, build.gradle 에 의존성을 명시해주었기 때문에 그냥 ./gradlew asciidoc 명령어 한번으로 충분하다.

생성된 문서 확인하기

위의 build.gradle 설정을 잘 따라했다면, 빌드 시에 자동으로 문서가 생성될 것이다.

 

 

위와 같은 문서가 생성된다.

레퍼런스

• Spring REST Docs 공식 문서
• 아샬님의 Spring REST Docs 간단히 써보기
• Asciidoctor gradle plugin 공식문서