백엔드
내가 만든 API를 널리 알리기 - Spring REST Docs 가이드편
두줄요약
Spring REST Docs의 테스트 기반 API 문서화와 Swagger 대비 선택 기준을 소개했습니다. OpenAPI 명세와 Swagger UI를 결합해 정적 문서와 API 호출 편의성을 함께 확보했습니다.
문제 상황
- 기존 Wiki 기반 API 문서의 낮은 활용성과 선물하기 시스템 재개발 과정의 문서화 필요
- 상세한 API 정보와 실제 동작 검증을 함께 보장할 문서화 방식 탐색
선택 이유
- Swagger의 풍부한 정보 제공 과정에서 운영 코드에 애노테이션이 추가되는 특성
- Spring REST Docs의 테스트 기반 스니펫 생성과 API 변경 누락의 즉각적 검증
- Asciidoc 조합을 통한 문서 구조 및 사용자 정의 스니펫 구성
구조와 흐름
- MockMvc·WebTestClient·REST Assured 기반 테스트 수행 후 스니펫 생성
- Asciidoctor로 스니펫을 HTML 문서로 렌더링
- REST Docs API specification Integration으로 OpenAPI YAML 생성 후 Swagger UI와 Postman 연동
트레이드오프
- Swagger UI의 즉시 호출·동적 문서화 장점과 보안 설정 필요성
- Spring REST Docs의 높은 신뢰성 대비 테스트, Asciidoc, Gradle 설정 및 작성 부담
- bootJar 패키징 시 REST Docs 산출물·Swagger UI·OpenAPI 파일 포함 구성
