Spring Rest Docs 정리 about be-tutorials

[pbg0205]

Spring REST Docs

1. API 문서를 자동화하는 도구.
2. 테스트를 성공해야 문서를 작성하기 때문에 API 의 신뢰도를 높히고 테스트 코드를 강제할 수 있는 장점이 있다.
3. production code 에 문서화를 위한 추가 코드가 작성되지 않기 때문에 코드의 가독성을 유지할 수 있다.

([Tecoble] API 문서 자동화 - Spring REST Docs 팔아보겠습니다)

Build Configuration (by. gradle)

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

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 { 
	snippetsDir = file('build/generated-snippets') // (5)
}

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

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

1. Asciidocttor plugin 을 적용한다.
2. Asciidoctor를 확장하는 dependency 에 대한 asciidoctorExt 구성을 선언한다.
3. asciidoctorExt 구성에서 spring-restdocs-asciidoctor에 대한 dependency 을 추가한다. 이렇게 하면 /build/generated-snippets 을 가리키는 .adoc 파일에서 사용할 snippets 속성을 자동으로 구성한다.
4. testImplementation 설정으로 spring-restdocs-mockmvc dependency 를 추가한다.
5. 생성된 snippet 의 출력 위치를 정의하도록 속성을 구성한다.
6. snippet 디렉토리를 생성하기 위해 test task 에 설정을 추가해야 한다.
7. asciidoctor task 를 설정한다.
8. 입력으로서의 snippet 디렉토리를 설정한다.
9. 확장에 대한 asciidoctorExt 사용을 환경 설정한다.
10. 문서가 생성되기 이전에 테스트가 실행되도록 task 가 test 에 의존하도록 설정한다.

([spring.io] Spring Rest Docs.Build configuration)

packaging the Documentation

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

1. jar이 빌드되기 전에 문서가 생성되었는지 확인한다.
2. 생성된 문서를 jar의 static/docs 디렉토리에 복사한다.