Spring REST Docs 트러블슈팅

문제 1. Asciidoctor 플러그인 Gradle 9 호환성 오류

원인

공식 문서 기준 Asciidoctor 플러그인 버전 3.3.2가 Gradle 9에서 제거된 구버전 API를 내부적으로 사용하고 있어 빌드 오류 발생

해결

Asciidoctor 플러그인을 최신 버전으로 업그레이드

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

문제 2. 플러그인 업그레이드 이후에도 빌드 오류 지속

원인

정확한 원인 미확인 (Asciidoctor 플러그인과 REST Docs 간 호환성 문제로 추정)

해결

AsciidoctorJ 버전을 명시적으로 지정하여 해결

asciidoctorj {
    version = "3.0.0"
}

문제 3. Spring Boot 4에서 @AutoConfigureRestDocs 누락

원인

Spring Boot 4에서 @AutoConfigureRestDocs의 패키지 경로가 변경되었는데, start.spring.io에서 REST Docs 의존성을 추가해도 해당 어노테이션이 포함된 spring-boot-restdocs 의존성이 자동으로 추가되지 않는 버그 (관련 이슈)

해결

의존성을 직접 추가