58.01_[Spring MVC] API 문서화_Spring Rest Docs 설정_22.11.14

>Spring Rest Docs 설정(build.gradle)

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

repositories {
	mavenCentral()
}

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

// (3)
configurations {
	asciidoctorExtensions
}

dependencies {
	// (4)
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
  
	// (5) 
	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
    
    ...
}

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

// (7)
tasks.named('asciidoctor') {
	configurations "asciidoctorExtensions"
	inputs.dir snippetsDir
	dependsOn test
}

// (8)
task copyDocument(type: Copy) {
	dependsOn asciidoctor            // (8-1)
	from file("${asciidoctor.outputDir}")   // (8-2)
	into file("src/main/resources/static/docs")   // (8-3)
}

build {
	dependsOn copyDocument  // (9)
}

// (10)
bootJar {
	dependsOn copyDocument    // (10-1)
	from ("${asciidoctor.outputDir}") {  // (10-2)
		into 'static/docs'     // (10-3)
	}
}

(1) Asciidoctor 플러그인 추가

(2) API 문서 스니핏이 생성될 경로 지정

: `ext` 변수의 `set()` 메서드를 이용

(3) AsciiDoctor에서 사용되는 의존 그룹을 지정 //명확히 모름

: :asciidoctor task가 실행되면 그룹 지정

(4) `spring-restdocs-core`, `spring-restdocs-mockmvc` 의존 라이브러리 추가

(5) `spring-restdocs-asciidoctor` 의존 라이브러리 추가

(6) :test task 실행 시, API 문서 생성 스니핏 디렉토리 경로를 설정

(7) :asciidoctor task에 asciidoctorExtensions 을 설정하여 :asciidoctor task 실행 시 Asciidoctor 기능을 사용 사용

(8) :copyDocument task 설정

:copyDocument task 가 수행되면 index.html 파일이 카피됨.

:copyDocument task는 :build task, :bootJar task 이전에 실행 됨.(9, 10번 참고)

(8-1) :asciidoctor task 가 실행된 후 :copyDocument task 가 실행되도록 설정

(8-2) 카피할 파일의 디렉토리를 지정(파일을 복사할 곳)

(8-3) 파일을 카피한 후 붙여넣을 디렉토리를 지정(파일이 생성될 곳)

//(8-3) 파일은 파일 자체로 외부에 제공할 목적의 html 파일

(9) :build task 설정

 :build task 가 실행되기전에 :copyDocument task가 실행되도록 설정.

(10) :bootJar task 설정

(10-1) :bootJar task 가 실행되기전에 :copyDocument task가 실행되도록 설정.

(10-2)

Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가.

(10-2) 과정으로 애플리케이션 실행 시 `http://localhost:8080/docs/index.html`에 접속하여 API 문서를 확인 할 수 있음.