[Springboot] Spring Rest Docs 적용(1) - build.gradle 빌드 구성

 

1. Spring Rest Docs?

Spring 기반의 RESTful API 프로젝트에서 API 문서를 생성하기 위한 도구

 

 

2. 프로젝트 빌드 구성

 

// build.gradle

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

configurations {
	asciidoctorExt (2)
}

dependencies {
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor:{project-version}' (3)
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc:{project-version}' (4)
}

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

tasks.named('test') { (6)
    useJUnitPlatform()
    outputs.dir snippetsDir
}

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

 

(1) Asciidoctor 플러그인 적용

Asciidoctor 플러그인은 Asciidoc이라는 텍스트 기반의 마크업 언어를 쉽게 활용할 수 있도록 도와주는 변환도구이자 라이브러리

adoc 파일을 HTML, PDF, EPUB 등 다양한 형식으로 변환하고 코드 블록에 대한 하이라이팅, IDE에서 문서 미리보기 기능 등을 제공

 

adoc 파일

 

AsciiDoc(아스키독) 포맷을 사용하는 텍스트 파일

AsciiDoc은 마크업 언어로, 문서를 구조화하고 서식을 지정하는 데 사용됩니다. 이는 특히 소프트웨어 문서, 기술 문서, 책, 블로그 게시물 등을 작성하는 데에 많이 사용됩니다.

AsciiDoc는 다른 마크업 언어들과 달리 일반 텍스트로 쓰여진 문서를 읽기 쉽게 유지하는 데 중점을 둡니다. 일반 텍스트로 작성되어 있기 때문에 소스 코드 관리 시스템에서도 쉽게 관리할 수 있습니다.

.adoc 파일을 사용하면 다양한 형식의 문서를 생성할 수 있습니다. 예를 들어, HTML, PDF, EPUB 등의 형식으로 변환할 수 있습니다. Spring REST Docs와 함께 사용될 때는 주로 HTML 형식으로 변환하여 API 문서를 생성하는 데 활용됩니다.

AsciiDoc 파일은 간단한 문법을 사용하며, 다양한 기능을 제공합니다. 예를 들어, 섹션 구분, 목록, 테이블, 코드 블록 등을 정의할 수 있습니다.

 

--> AsciiDoc 파일을 빌드하여 다양한 형식으로 출력물을 생성하는 도구들이 있습니다. AsciiDoctor는 이러한 도구 중 하나로, Spring REST Docs에서는 Maven 또는 Gradle 플러그인을 통해 AsciiDoctor를 사용하여 HTML 문서를 생성합니다. 

--> Asciidoctor 플러그인은 AsciiDoc 형식의 문서를 다른 형식으로 변환합니다. 주로 HTML, PDF, EPUB 등의 형식으로 변환하여 문서를 생성합니다.

--> Spring REST Docs와 함께 사용되는 경우, Asciidoctor 플러그인은 테스트에서 생성된 스니펫 파일들을 AsciiDoc 문서로 변환하고, 이를 HTML 형식으로 렌더링하여 API 문서를 생성합니다. Maven 또는 Gradle 빌드 과정에서 이러한 작업이 자동으로 수행되어 문서 생성이 간편하게 이루어집니다.

 

(2) Asciidoctor를 확장하는 종속성에 대한 asciidoctorExt 구성을 선언

Asciidoctor를 확장하는 종속성: Asciidoctor의 기능을 확장하거나 향상시키는 라이브러리나 플러그인을 말함

-> Asciidoctor 기능 향상 시키는 라이브러리나 플러그인의 의존성을 추가하려고 asciidoctorExt라는 configuration(구성)을 정의

이렇게 하면 dependencies {} 블록에서 asciidoctorExt 구성에만 의존성을 추가할 수 있음( 3번이 그 예시가 될 수 있음) 

 

configuration 블록

configuration 블록은 Maven Central Repository와 같은 원격 저장소에서 라이브러리를 가져와 프로젝트에 추가할 때 사용됨

1. 의존성 추가 및 제어:
   • implementation, compileOnly, testImplementation 등과 같은 구성을 사용하여 프로젝트에 필요한 의존성을 추가하거나 특정 구성에만 의존성을 추가할 수 있습니다.
2. 테스트와 관련된 설정:
   • 테스트 실행 시에 필요한 의존성을 추가하고 관리하는 데 사용됩니다. 예를 들어, testImplementation 구성을 통해 테스트에만 필요한 라이브러리를 추가할 수 있습니다.
3. 사용자 지정 구성 추가:
   • 특별한 사용자 지정 구성을 추가하여 프로젝트의 특정 요구 사항에 맞게 의존성을 관리할 수 있습니다.

 

(3) asciidoctorExt 구성에 spring-restdocs-asciidoctor 종속성 추가

그러면 .adoc파일에서 사용할 snippets 속성이 자동으로 build/generated-snippets을 가리키도록  구성됨

또한 operation블록 매크로를 사용할 수 있음

 

(4) testImplementation 구성에 spring-restdocs-mockmvc 종속성 추가

MockMvc 대신 WebTestClient 또는 REST Assured를 사용하려면  spring-restdocs-webtestclient또는 spring-restdocs-restassured 각각에 대한 종속성 추가해야함

 

(5) 생성된 snippets의 저장할 경로를 snippetsDir에 정의하는 속성 구성

 

(6) Gradle이 test작업을 실행하면 출력이 snippetsDir에 기록된다는 점을 인식하게 해야함(이는 Incremental 빌드에 필요)

 

(7) asciidoctor 작업 구성

(8) asciidoctor 작업을 실행하면 snippetsDir에서 입력을 읽게 된다는 점을 Gradle이 인식하게함(이는 Incremental 빌드에 필요)

(9) 'asciidoctorExt 확장에 대한 구성'인 asciidoctorExt를 사용할 것을 구성

(10) asciidoctor의 작업인 '문서 작성' 전에 테스트가 실행되도록 test작업을 의존함

 

 

3. 요약

1) Asciidoctor 플러그인은 테스트에서 생성된 snippets(코드 조각) 파일들을 AsciiDoc 문서로 변환하고, 이를 HTML 형식으로 렌더링하여 API 문서를 생성하기 위해서 설치

2) Asciidoctor 플러그인에 의존하는 종속성(예를들면 아래  spring-restdocs-asciidoctor)을 의존시키기 위해 asciidoctorExt 구성을 만듦

3) asciidoctorExt 구성에 spring-restdocs-asciidoctor 의존성을 추가함(이 의존성은 .adoc파일에서 사용할 snippets 속성이 자동으로 build/generated-snippets을 가리키도록  구성됨)

4) asciidoctorExt 구성에 spring-restdocs-mockmvc 의존성을 추가함(test 작업을 하기 위해서)

5) 코드 스니펫이 저장될 경로(snippetsDir)를 정함

6) Gradle이 test작업을 실행하면 출력이 snippetsDir에 기록하는 것을 인식하게 함

7 ~ 10) asciidoctor 작업 구성(asciidoctor는 작업 실행시 snippetsDir에서 입력을 읽고, asciidoctorExt 구성을 사용하고, asciidoctor 작업인 문서 작성 전에 test가 선 실행 되야 하는 것을 설정)

 

 

Spring REST Docs 공식 문서

https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/#getting-started

Spring REST Docs