Spring Rest Docs

일단 Spring REST DOCS의 정의

1) Spring MVC TEST에 의해 2) 자동 생성된 snippet과 3) 직접 작성한 문서를 결합하여 최종 Documentation을 만들어 주는 서비스

gradle 8.7

springboot 3.2.4

java 17

plugins {
		id 'org.springframework.boot' version '2.5.5'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    id 'org.asciidoctor.jvm.convert' version '3.3.2' // (1) 
}

configurations {
    asciidoctorExt // (2)
}

dependencies {
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor' // (3)
	...
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:2.0.4.RELEASE'// (4)
}

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

test {
    outputs.dir snippetsDir // (6)
}

asciidoctor { // (7)
	configurations 'asciidoctorExt' // (8)
    inputs.dir snippetsDir // (9)
    dependsOn test    //(10)
}

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

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

build {
    dependsOn copyDocument
}

(1)

AsciiDoc 파일을 컨버팅하고 Build 폴더에 복사하기 위한 플러그인입니다.

gradle7부터는 asciidoctor.jvm.convert 적용해야한다. 이 전에는 org.asciidoctor.convert

(2)

asciidoctor를 확장하는 asciidoctorExt 에 대한 종속성 구성을 선언한다.

종속성 구성이란 ?

dependencies에서 종속성을 구성하는데 종속성 선언은 (종속성 구성) (group):(name):(version) 으로 선언할 수 있다.

종속성은 구성(configurations)으로 그룹화된다.

구성에 대한 특정 종속성을 선언하려면 configurations을 사용하면 된다.

(3)

asciidoctorExt에 spring-restdocs-asciidoctor 의존성을 추가한다. 이 종속성이 있어야 build/generated-snippets에 있는 .adoc 파일을 읽어들여 .html 파일로 만들어낼 수 있다.

snippets이란 ?

REST API에 대한 정보를 담고 자동 생성되는 `.adoc` 문서*

(4)

MockMvc를 사용하기 위한 의존성을 추가한다. MocMvc 대신에 WebTestClient를 사용하려면 spring-restdocs-webtestclient을, RestAssured를 사용하려면 spring-restdocs-restassured을 대신 사용한다.

(5)

전역 변수를 설정해주는 것 , gradle은 build/generated-snippets에 스니펫이 생성되므로, 스니펫 생성 디렉토리를 변수에 담아준다.
(6)

스니펫을 snippetsDir로 생성하도록 test 태스크를 설정한다.

(7)

asciidoctor 태스크에 대한 설정을 한다.

(8)

Asciidoctor 확장에 대한 설정을 한다.

(9)

불러올 스니펫 위치를 snippetsDir로 설정한다.

(10)

test 태스크 이후에 asciidoctor를 실행하도록 설정한다.

gradle build 시 test -> asciidoctor 순으로 수행

(11)

기존에 있던 html파일들 삭제

doFirst??

순서

테스트 코드 작성

테스트 코드 실행 → generated-snippets에 adoc파일 자동 생성

(+ adoc 파일 자동생성 된거 보고 직접 만들어준 src/docs/asciidoc 경로에도 자동생성된 adoc파일 합치는 adoc파일 하나 더 만들어야함)

gradle build 실행 → adoc(직접만들어준)파일이 html로 변환됨

프로젝트 실행 → http://localhost:8080/docs/index.html 로 접속하면 나옴

• build 실행시켜야 html 생성
• src/docs/asciidoc 경로(직접 만들어줘야함)에 .adoc 파일이 있을시에

실제로 구현한 코드는 아래 링크 참고
https://github.com/xxhyxxnjxn/spring-rest-docs