tosspayments-restdocs: 선언형 문서 작성 라이브러리

Spring REST Docs는 API 통합 테스트와 인터페이스 변경 감지에 유용하지만, 반복적인 명세와 MockMvc 세부 구현에 대한 의존으로 코드가 장황하고 유지보수가 어려웠습니다. 이를 개선하기 위해 HTTP 페이로드를 Documentation, Request Line, Request Body 같은 요소로 표현하는 Kotlin DSL 라이브러리 tosspayments-restdocs를 만들었습니다. 필수 정보는 함수 파라미터로, 추가 설정은 람다 확장 함수 스코프로 구성하고, 샘플에 Reified 타입 정보를 보존해 타입 명세와 열거형 예시 등을 자동화했습니다. 그 결과 문서화 코드가 줄고 인터페이스 명세에 집중할 수 있었으며, 기반 기술이나 문서 항목의 변화에도 확장하기 쉬운 구조를 얻었습니다.

• 문서화 코드는 HTTP 요청과 응답의 흐름에 맞춰 구성하면 읽는 사람이 결과를 위에서 아래로 파악하기 쉽습니다.
• Kotlin DSL에서는 필수 속성을 함수 파라미터로, 선택적인 세부 설정을 람다 확장 함수 스코프로 분리할 수 있습니다.
• 중첩된 스코프를 활용하면 문서 요소의 계층을 코드에 드러내면서 새 속성이나 하위 요소를 확장하기 쉽습니다.
• Inline 함수의 Reified 타입 파라미터로 샘플의 타입 정보를 보존하면 필드 타입이나 열거형 예시, 포맷을 자동 생성할 수 있습니다.