Spring API문서화 2/2 Spring RestDocs #Day20

Controller의 슬라이스 테스트를 통해 테스트가 통과(”PASSED”)되어야지만 API 문서가 정상적으로 생성됨 API 스펙 정보와 API 문서 정보의 불일치로 인해 발생하는 문제를 방지 Swagger는 애너테이션 내에 API 스펙 정보를 문자열로 입력하기 때문에 API 스펙 정보와 API 문서 내의 정보가 불일치 할 수 있음 Swagger처럼 API를 호출해볼 수 있는 툴의 역할은 없음

Spring Rest Docs사용을 위한 설정

• 슬라이스 테스트 코드 작성 →API 스펙 정보 코드 작성 →test 태스크 실행 →API 문서 스니펫 생성스니펫을 포함한 API 문서 생성.adoc 파일의 API 문서를 HTML로 변환
• Spring Rest Docs를 사용해서 API 문서를 생성하기 위해서는 .adoc 문서 스니펫을 생성해 주는 Asciidoctor가 필요

build.gradle

• 아래 경로에 디렉토리를 생성 : src/docs/asciidoc/
• 비어있는 템플릿 문서(index.adoc)를 생성

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

plugins { ...
	id "org.asciidoctor.jvm.convert" version "3.3.2"    // (1) AsciiDoc 문서를 생성해 주는 Asciidoctor를 사용하기 위한 플러그인을 추가
}

// (2) API 문서 스니펫이 생성될 경로를 지정
ext {
	set('snippetsDir', file("build/generated-snippets"))
}

// (3) AsciiDoctor에서 사용되는 의존 그룹을 지정
// asciidoctor task가 실행되면 내부적으로 ‘asciidoctorExtensions’라는 그룹으로 지정
configurations {
	asciidoctorExtensions
}

dependencies { ...
  // (4) 의존성 라이브러리 추가
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
	asciidoctorExtensions 'org.springframework.restdocs:spring-restdocs-asciidoctor'
}

// (6) test task 실행 시, API 문서 생성 스니펫 디렉토리 경로를 설정
tasks.named('test') {
	outputs.dir snippetsDir
	useJUnitPlatform()
}

// (7) asciidoctor task 실행 시, Asciidoctor 기능을 사용하기 위해 :asciidoctor task에 asciidoctorExtensions을 설정
tasks.named('asciidoctor') {
	configurations "asciidoctorExtensions"
	inputs.dir snippetsDir
	dependsOn test
}

// (8) build task 실행 전에 실행되는 task
// copyDocument task가 수행되면 index.html 파일이 src/main/resources/static/docs 에 copy 되며, copy 된 index.html 파일은 API 문서를 파일 형태로 외부에 제공하기 위한 용도로 사용
task copyDocument(type: Copy) {
	dependsOn asciidoctor            // (8-1) asciidoctor task가 실행된 후에 task가 실행되도록 의존성을 설정
	from file("${asciidoctor.outputDir}")   // (8-2) "build/docs/asciidoc/" 경로에 생성되는 index.html을 copy한 후,
	into file("src/main/resources/static/docs")   // (8-3) "src/main/resources/static/docs" 경로로 index.html을 추가
}

build {
	dependsOn copyDocument  // (9) build task가 실행되기 전에 :copyDocument task가 먼저 수행되도록 함

// (10) 애플리케이션 실행 파일이 생성하는 :bootJar task 설정
bootJar {
	dependsOn copyDocument    // (10-1) bootJar task 실행 전에 :copyDocument task가 실행되도록 의존성을 설정
	from ("${asciidoctor.outputDir}") {  // (10-2) Asciidoctor 실행으로 생성되는 index.html 파일을 jar 파일 안에 추가
		into 'static/docs'     // (10-3)
	}
}