특징

테스트 코드를 통한 API 문서 자동화 도구

API 명세를 문서로 만들고 외부에 제공함으로써 협업을 원할하게 한다.

기본적으로 AsciiDoc을 사용하여 문서를 작성한다.

• MarkDown과 같은 문법을 사용하여 문서를 작성하는 것

Rest Docs와 Swagger 차이

• 프로덕션 코드에 비침투적 | - 코드양이 많고 설정이 어려움 | | Swagger | 적용이 쉽고 문서에서 바로 API 호출을 수행할 수 있음 | - 프로덕션 코드에 침투적이다.
• 테스트와 무관하기 때문에 신뢰도가 떨어질 수 있다. |

설정

Gradle 설정 추가

• plugins

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

• configuartions

configurations {
	compileOnly {
		extendsFrom annotationProcessor 
	}
	asciidoctorExt
}

• dependenies

dependencies {
	// RestDocs
	asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
	testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc' // restDocs 사용 시 mockmvc 주로 사용

}

• 그 외

tasks.named('test') {
	useJUnitPlatform()
}

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

test {
	outputs.dir snippetsDir
}

asciidoctor {
	inputs.dir snippetsDir
	configurations 'asciidoctorExt'

	sources { // 특정 파일만 html로 만든다.
		include("**/index.adoc")
	}
	baseDirFollowsSourceFile() // 다른 adoc 파일을 include 할 때 경로를 baseDir로 맞춘다.
	dependsOn test
}

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