tosspayments-restdocs: 선언형 문서 작성 라이브러리
이준희 토스 · 토스 기술 블로그
AI 핵심 요약
Spring REST Docs는 API 통합 테스트와 인터페이스 변경 감지에 유용하지만, 반복적인 명세와 MockMvc 세부 구현에 대한 의존으로 코드가 장황하고 유지보수가 어려웠습니다. 이를 개선하기 위해 HTTP 페이로드를 Documentation, Request Line, Request Body 같은 요소로 표현하는 Kotlin DSL 라이브러리 tosspayments-restdocs를 만들었습니다. 필수 정보는 함수 파라미터로, 추가 설정은 람다 확장 함수 스코프로 구성하고, 샘플에 Reified 타입 정보를 보존해 타입 명세와 열거형 예시 등을 자동화했습니다. 그 결과 문서화 코드가 줄고 인터페이스 명세에 집중할 수 있었으며, 기반 기술이나 문서 항목의 변화에도 확장하기 쉬운 구조를 얻었습니다.
- 문서화 코드는 HTTP 요청과 응답의 흐름에 맞춰 구성하면 읽는 사람이 결과를 위에서 아래로 파악하기 쉽습니다.
- Kotlin DSL에서는 필수 속성을 함수 파라미터로, 선택적인 세부 설정을 람다 확장 함수 스코프로 분리할 수 있습니다.
- 중첩된 스코프를 활용하면 문서 요소의 계층을 코드에 드러내면서 새 속성이나 하위 요소를 확장하기 쉽습니다.
- Inline 함수의 Reified 타입 파라미터로 샘플의 타입 정보를 보존하면 필드 타입이나 열거형 예시, 포맷을 자동 생성할 수 있습니다.
소개
REST Docs 를 최소한의 코드로 작성하면서 변화에도 더 유연하게 대처할 수 있는 tosspayments-restdocs 라이브러리와, 라이브러리에 녹인 기술들을 소개합니다.
비슷한 학습 자료
문서 한주연
The Toss Frontend team no longer has to dig through documents to find what they need. We’re building an environment where developers can get immediate answers to their questions through docs and AI. Here’s how we built a new documentation system that lets developers focus entirely on development.
프론트엔드 AI에이전트 개발
문서 이주함
쓰기 쉬운 Toss Front SDK
문서 한주연/신지호
