Spring Rest Docs

• Production 코드에 영향 x (Swagger처럼 어노테이션 범벅x) | - 테스트 코드 양이 많아진다
• 설정이 복잡하다
• API 호출 테스트를 문서 자체에서 지원하진 x |

공식 문서

https://docs.spring.io/spring-restdocs/docs/current/reference/htmlsingle/#introduction

최소 요구사항

• Java 17
• Spring Framework 6

build.gradle

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

configurations {
    asciidoctorExt // ②
}

dependencies {
    //..
    
    //③
    asciidoctorExt 'org.springframework.restdocs:spring-restdocs-asciidoctor'
    testImplementation 'org.springframework.restdocs:spring-restdocs-mockmvc'
}

ext { // ④
    snippetsDir = file("${layout.buildDirectory.asFile.get()}/generated-snippets")
}

test {
    outputs.dir snippetsDir  // ⑤
    useJUnitPlatform()
}

asciidoctor.doFirst { // ⑥
    delete file("src/main/resources/static/docs")
}

asciidoctor { // ⑦
    configurations 'asciidoctorExt'
    baseDirFollowsSourceDir()
    inputs.dir snippetsDir
    dependsOn test
}

task createDocument(type: Copy) { // ⑧
    dependsOn asciidoctor
    from file("${layout.buildDirectory.asFile.get()}/docs/asciidoc")
    into file("src/main/resources/static/docs")
}

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

// test > asciidoctor > createDocument > build
build {
    dependsOn createDocument
}

① asciidoc 문서를 html, pdf 등 다양한 형식으로 변환하는데 사용되는 gradle 플러그인

• Spring Rest Docs에서 생성한 snippets 포함한 asciidoc 문서를 html 변환하여 API 문서 생성 지원

② configuration

• 빌드 작업에서 필요한 의존성만 포함하도록 제한하는 역할

③ 의존성 추가