내가 만든 API를 널리 알리기 - Spring REST Docs 가이드편

간단 소개

Spring REST Docs를 활용한 API 문서화 및 Swagger UI 통합 가이드: 컬리 기술 블로그 사례를 중심으로 설명합니다.

AI Summary

Spring REST Docs 도입 배경
- 컬리 '추석맞이 선물하기' 재개발 프로젝트에서 API 문서화를 위해 Spring REST Docs를 도입
- 기존 Wiki 문서의 한계를 극복하고, Swagger의 운영 코드 침투성을 피하고자 함
Spring REST Docs vs Swagger
- Swagger는 운영 코드에 애노테이션 추가가 필요하며, Spring REST Docs는 테스트 코드 작성을 강제함
- Spring REST Docs는 테스트 기반으로 스니펫을 생성하여 API 문서의 신뢰성을 높임
- Spring REST Docs의 정적인 HTML 문서의 단점을 보완하기 위해 Swagger UI를 통합하여 API 테스트 기능 추가
Spring REST Docs와 Swagger UI 통합
- Spring REST Docs 테스트 코드를 활용하여 OpenAPI Specification(OAS) 문서를 생성하고 Swagger UI로 시각화
- Spring REST Docs API specification Integration을 통해 OAS 문서를 JSON 또는 YAML 형식으로 생성 가능
- Swagger UI를 통해 API 테스트를 지원하고, Spring REST Docs의 활용도를 높임