Spring REST Docs 초기 설정

공식 문서

Spring REST Docs 공식 문서

참고

Practical Testing: 실용적인 테스트 가이드 강의 영상

빌드 구성

REST Docs을 사용하기 위한 기본적인 빌드 구성입니다.
포스팅 중간에 추가적인 구성들이 추가됩니다.

// build.gradle

plugins {
    id "org.asciidoctor.jvm.convert" version "3.3.2"
}

configurations {
    asciidoctorExt
}

dependencies {
    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

ext { // 전역 변수
    snippetsDir = file('build/generated-snippets')
}

test {
    outputs.dir snippetsDir
}

asciidoctor {
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'
    dependsOn test
}

bootJar {
    dependsOn asciidoctor
    from ("${asciidoctor.outputDir}") {
        into '/static/docs'
    }
}

REST Docs를 사용할 상위 클래스 정의

Spring REST Docs는 MockMvc, WebTestClient, REST Assured로 만들어질 수 있습니다.
본 예제에서는 MockMvc를 사용합니다.

@ExtendWith(RestDocumentationExtension.class)
public abstract class RestDocsSupport {

    protected MockMvc mockMvc;

    @BeforeEach
    void setup(RestDocumentationContextProvider provider) {
        this.mockMvc = MockMvcBuilders.standaloneSetup(initController())
                .apply(documentationConfiguration(provider))
                .build();
    }

    protected abstract Object initController();
}

REST Docs를 사용할 하위 클래스 구현

@RequestMapping("/")
@RestController
public class HealthCheckController {

    @GetMapping(
            produces = "text/html; charset=UTF-8"
    )
    public String healthCheck() {
        return "애플리케이션이 실행중입니다!";
    }
}

하위 테스트 클래스는 위 API에 대한 테스트 케이스입니다.

class HealthCheckControllerDocsTest extends RestDocsSupport {

    @Override
    protected Object initController() {
        return new HealthCheckController();
    }

    @DisplayName("실행중이라면 실행 중이라는 메시지를 준다.")
    @Test
    void healthCheck() throws Exception {
        mockMvc.perform(get("/"))
                .andDo(print())
                .andExpect(status().isOk())
                .andExpect(content().string("애플리케이션이 실행중입니다!"))
                .andDo(document("health-check",
                        responseBody()
                ));
    }
}

테스트를 통과하고, build/generated-snippets에 .adoc 형식으로 문서 조각이 생깁니다.
이제 문서 조각을 모아서 문서를 만들어 주어야 합니다.

// src/docs/asciidoc/index.adoc

ifndef::snippets[]
:snippets: ../../build/generated-snippets
endif::[]
= time-slot REST API 문서
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 2
:seclinks:

[[HealthCheck-API]]
== HealthCheck API

[[health-check]]
=== 애플리케이션 상태 확인

==== HTTP Request

include::{snippets}/health-check/http-request.adoc[]

==== HTTP Response

include::{snippets}/health-check/http-response.adoc[]

성공한 테스트로 만들어진 문서 조각들로 문서를 완성합니다.
하지만 index.adoc 에 API를 추가할수록 문서가 길어집니다.
이러한 문제를 문서를 분리해서 관리하고 build시에 합친다면 관리하기가 용이해집니다.

// src/docs/asciidoc/healthcheck/health-check.adoc

[[health-check]]
=== 애플리케이션 상태 확인

==== HTTP Request

include::{snippets}/health-check/http-request.adoc[]

==== HTTP Response

include::{snippets}/health-check/http-response.adoc[]

// src/docs/asciidoc/index.adoc

ifndef::snippets[]
:snippets: ../../build/generated-snippets
endif::[]
= time-slot REST API 문서
:doctype: book
:icons: font
:source-highlighter: highlightjs
:toc: left
:toclevels: 2
:seclinks:

[[HealthCheck-API]]
== HealthCheck API

include::healthcheck/health-check.adoc[]

분리하였음에도 미리보기가 잘 출력되는 것을 확인할 수 있습니다.
이제 asciidoctor 를 돌려보면 아래와 같은 문제가 발생합니다.

두 가지 문제가 있습니다.
1. health-check.adoc 경로를 찾지 못하는 문제
2. html 파일이 2개 생성되는 문제

// build.gradle

asciidoctor {
    inputs.dir snippetsDir
    configurations 'asciidoctorExt'

    sources {
        include("**/index.adoc")
    }
    baseDirFollowsSourceDir()
    dependsOn test
}

asciidoctor 작업을 위와 같이 수정한 뒤, clean -> asciidoctor 돌리게 되면 정상적으로 만들어 집니다.

build 작업을 하면 build/libs 에 jar 파일이 생성됩니다. build 작업한 뒤, java -jar projectName-SNAPSHOT.jar 로 실행하게 되면 localhost:8080/docs/index.html 경로에 문서 있는 것을 볼 수 있습니다.