실행 환경

• java : 11
• gradle : 7.4.1

Spring Rest Docs

• 먼저 전 프로젝트에서 사용했던 Rest Docs를 보겠습니다.

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'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '11'

configurations {
    asciidoctorExtensions   // (2)
}

repositories {
    mavenCentral()
}

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

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

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

tasks.named('asciidoctor') {  // (6)
    configurations 'asciidoctorExtensions'
    sources{
        include("**/index.adoc")
    }
    baseDirFollowsSourceFile()
    inputs.dir snippetsDir
    dependsOn test
}

asciidoctor.doFirst {     //(7)
    delete file('src/main/resources/static/docs')
}

task createDocument(type: Copy) {       // (8)
    dependsOn asciidoctor

    from file("build/docs/asciidoc")
    into file("src/main/resources/static")
}

bootJar {       // (9)
    dependsOn createDocument
}

• (1) : gradle 7버전부터는 org.asciidoctor.jvm.convert 을 사용해야 합니다.
• (2) : asciidoctorExtensions 을 설정해줍니다.
• (4), (5) : asciidoctorExtensions 과 docs 생성을 위한 spring-restdocs-mockmvc 의존성을 추가해줍니다.
• (6) : dependsOn으로 test task가 실행된 이후 실행되는 task입니다.
  • sources에 명시한 adoc만 html로 변환하게 해줍니다.
  • baseDirFollowsSourceFile의 경우 docs/asciidoctor/domain과 같이 폴더 구조로 adoc을 만들었을 때 index.adoc에서 include했을 경우 path를 찾지 못하기 때문에 설정해줘야 합니다.
• (7) : 문서 최신화를 위해 앞전에 만들었던 docs파일을 삭제합니다. doFirst로 인해 asciidoctor가 실행되기 전에 실행하게 됩니다.
• (8) : 완성된 html을 static 폴더에 넣어 서버를 띄우게 되면 볼 수 있도록 합니다.
• (9) : bootJar가 실행되기 전에 createDocument task를 실행하게 됩니다.
  • 이를 통해 build시에 docs파일이 jar파일에 들어갈 수 있습니다.

적용

@RestController
public class TestController {

	@GetMapping("/users")
	public ResponseEntity<TestResponse> get() {
		return ResponseEntity.ok(new TestResponse("test"));
	}