Spring REST Docs + asciidoctor 로 문서 자동 생성해보기

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 를 통한 테스트 코드로 문서를 생성하기 위해서 필요하다.

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')
}

copyDocument task 생성하기

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

build 에 의존성 걸기

build {
    dependsOn copyDocument
}

• build 할 때, 문서를 복사하도록 한다.

문서 생성하기

테스트 코드를 이용하여 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"));
}

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[]

asciidoc task 수행하기

./gradlew asciidoc

• 사실 test task 를 수행하지 않아도, 의존성이 걸려있기 때문에 index.adoc 파일이 제자리에 존재한다면 이 명령어만 수행해도 잘 된다.

레퍼런스

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