Spring Rest Docs에 대해서

Spring Rest Docs

• Spring 기반의 애플리케이션을 위한 문서화 도구

• Spring REST Docs는 실제 테스트 케이스를 기반으로 작동

  • 이는 문서가 실제 애플리케이션의 동작과 일치하도록 보장

• Spring REST Docs는 Asciidoctor를 사용하여 문서를 작성하고,

• 테스트 중에 API의 요청과 응답을 자동으로 캡처하여 문서화한다

간단 요약

개발자가 API의 변경 사항을 쉽게 문서화하고, API 사용자에게 정확한 정보를 제공한다.

Controller 패키지를 테스트를 한뒤, 테스트가 성공했을때만 API 문서를 작성해주는 도구다.

📎 **`Swagger` 와의 차이**

Swagger는 Spring MVC의 테스트를 실행하지 않고 문서를 생성하기 때문에 실제로 API가 동작하는지 확인할 수 없다.

Swagger는 API의 스펙을 정의하는 것이 목적

Spring Rest Docs는 API의 스펙을 정의하고 테스트하는 것이 목적이다.

또한 Swagger 는 비지니스 로직 코드와 문서를 분리하기 어렵다.

Asciidoctor

Spring REST Docs는 Asciidoctor와 통합되어 API 문서를 생성한다.

REST Docs는 테스트를 통해 API 사용 방법을 설명하는 문서 스니펫을 생성하고, 이러한 스니펫들을 Asciidoctor 문서에 포함시킨다.

Asciidoctor는 AsciiDoc 문서 포맷을 HTML, PDF 등 다양한 형식으로 변환할 수 있는 강력한 도구이다.

Spring Rest Docs에서 Asciidoctor가 하는 역할

1. 문서 변환: Spring REST Docs는 API의 사용 방법을 설명하는 데 필요한 스니펫(예: HTTP 요청/응답, cURL 명령어, JSON 응답 본문 등)을 생성한다. Asciidoctor는 이러한 스니펫과 AsciiDoc 문법으로 작성된 문서를 HTML, PDF 등 다양한 형식의 최종 문서로 변환한다.
2. 문서 통합: Asciidoctor를 사용하면, 개발자는 테스트 케이스에서 생성된 스니펫을 AsciiDoc 문서에 쉽게 통합할 수 있다. 이는 문서화 과정을 자동화하고, 문서의 정확성과 일관성을 보장하는 데 도움이 된다.
3. 풍부한 문서 포매팅: Asciidoctor는 텍스트, 표, 이미지, 코드 블록 등 다양한 문서 요소를 지원한다. 이를 통해 개발자는 API 문서를 보다 명확하고 이해하기 쉽게 만들 수 있으며, 사용자가 API를 더 쉽게 배우고 사용할 수 있도록 돕는다.
4. 확장성과 유연성: Asciidoctor는 사용자 정의 테마, 매크로 확장 등을 통해 문서의 외관과 구조를 사용자의 요구에 맞게 조정할 수 있게 해준다. 이를 통해 기업이나 프로젝트의 브랜딩 요구사항에 맞는 문서를 생성할 수 있다.

---

Keeper 홈페이지에 build.gradle.kts에 설정된 부분 뜯어보기

Spring REST Docs와 Asciidoctor를 사용하여 API 문서를 자동으로 생성하고, 생성된 문서를 Spring Boot 애플리케이션의 일부로 만들어 배포하는 과정을 자동화하는 코드…

/******* Start Spring Rest Docs *******/ //(Gradle 빌드 스크립트의 일부로, Kotlin DSL)

val asciidoctorExt: Configuration by configurations.creating //  Asciidoctor 확장을 위한 Gradle 설정을 정의
val snippetsDir by extra { "$buildDir/generated-snippets" } // 스니펫(snippets)을 저장할 디렉토리의 경로

tasks {
    withType<KotlinCompile> { // 컴파일러 설정을 정의
        kotlinOptions {
            freeCompilerArgs = listOf("-Xjsr305=strict")
            jvmTarget = "17"
        }
    }
    withType<Test> { // JUnit 플랫폼을 사용하여 테스트를 실행하는 설정
        useJUnitPlatform()
    }
    test {
        useJUnitPlatform() //  Asciidoctor 작업을 설정하여, 스니펫을 포함한 문서를 생성
        outputs.dir(snippetsDir)
    }
    asciidoctor {
        doFirst {
            project.delete(files("src/main/resources/static/docs"))
        }
        inputs.dir(snippetsDir)
        configurations("asciidoctorExt")
        dependsOn(test)
        baseDirFollowsSourceFile()
    }
    register<Copy>("copyDocs") { // Asciidoctor 작업에 의해 생성된 문서를 애플리케이션의 정적 리소스 디렉토리로 복사
        dependsOn(asciidoctor)
        from("${asciidoctor.get().outputDir}")
        into("src/main/resources/static/docs")
    }
    bootJar {  /Spring Boot의 실행 가능한 JAR 파일을 생성하는 작업에 Asciidoctor 문서를 포함
        dependsOn(asciidoctor)
        from("${asciidoctor.get().outputDir}") {
            into("static/docs")
        }
    }
    build { // copyDocs 작업에 의존하도록 설정하여, 빌드 프로세스 중에 문서가 복사되고 포함되도록
        dependsOn("copyDocs")
    }
}
/******* End Spring Rest Docs *******/

asciidoctorExt("org.springframework.restdocs:spring-restdocs-asciidoctor")
testImplementation("org.springframework.restdocs:spring-restdocs-mockmvc")

---

단점

1. 초기 설정 복잡성

• Spring REST Docs를 처음 설정할 때는 약간의 학습 곡선과 초기 설정 작업이 필요하다. 테스트 케이스에 문서화 과정을 통합하고, Asciidoctor와 같은 도구를 설정하는 데 시간이 걸릴 수 있다.

2. 테스트 작성 필요성

• 문서가 테스트 케이스와 함께 생성되기 때문에, 문서화하고자 하는 API에 대한 충분한 테스트 케이스를 작성해야 합니다. 이는 추가적인 작업 부담을 의미할 수 있다.

3. 유지 관리

• API가 변경될 때마다 관련 테스트 케이스를 업데이트하고 문서를 재생성해야한다. API가 자주 변경되는 경우, 이 과정이 번거로울 수 있다.

4. 테스트 기반 접근의 한계

• 테스트를 기반으로 문서를 생성한다는 점은 장점이 될 수 있지만, 테스트가 커버하지 못하는 부분은 문서에 반영되지 않는다. 따라서, 완전한 문서화를 위해서는 모든 가능한 시나리오를 테스트로 커버해야 한다.

5. 특정 기술 스택에 의존

• Spring REST Docs는 Spring 기반 애플리케이션에 특화되어 있으며, Spring 프레임워크나 Spring Boot와 함께 사용하기 위해 설계되었다. 다른 기술 스택을 사용하는 프로젝트에서는 이를 직접 사용하기 어려울 수 있다.

6. 동적인 내용의 한계

• 정적 문서화 도구인 만큼, 동적으로 변하는 내용이나 사용자 상호작용을 기반으로 한 문서의 부분을 표현하는 데 한계가 있다. 예를 들어, 사용자 입력에 따라 변하는 API 응답을 문서화하는 경우, 다양한 시나리오를 모두 테스트로 커버해야 한다.