Spring 진영에서 API 문서화에 관심이 있다면 Swagger와 RestDocs를 한번쯤은 사용해봤거나 들어는 봤을 것이다.이번 문서에서는 Swagger, RestDocs 이 두가지의 장점만을 모아 Kotlin DSL로 리팩토링한 과정에 대해서 소개합니다. 커스텀 DSL 미리보기Swagger 라이브러리 문제점Swagger 사용법에 대해 검색해 보면, 컨트롤러나 사용하는 요청DTO, 응답DTO에 애너테이션을 선언하는 방식을 주로 설명하는 것을 확인할 수 있었다.이 방법은 간단하지만, 경험상 몇가지 문제가 있다는 것을 느낄 수 있었다.컨트롤러나 DTO를 봤을 때, 수 많은 애너테이션으로 인해 가독성 저하가 발생한다.수기 작성이다 보니 문서화에 필요한 타입이나 값들이 검증되지 않은 상태로 등록될 수 있다...

아무런 설정없이 문서를 작성하면 요청 파라미터나 요청 헤더 값에 대한 설명은 작성할 수 있지만 필수값(Required) 표현이 안 되었다. 그 이유는 기본적으로 제공되는 스니펫 규격이 정해져있기 때문이다. default-request-headers.snippet 파일 |=== |Name|Description {{#headers}} |{{#tableCellContent}}`+{{name}}+`{{/tableCellContent}} |{{#tableCellContent}}{{description}}{{/tableCellContent}} {{/headers}} |=== 스니펫들 중 하나를 선택해 읽어보면 name, descripton 속성만 있는 것을 확인할 수 있다. 필수값을 표현할 수 있는 방법을 알아보던..