이번 포스팅에서는 문서화 작업시에 REST API 의 요청 파라미터 혹은 요청 body payload 의 각 항목에 대한 제약사항을 문서화에 추가하는 방법에 대해서 기술한다. 이전 포스팅의 샘플 코드를 기반으로 내용을 발전시켜 나가겠다. Validation 디펜던시 추가 이전 포스팅의 pom.xml 에서 validation 디펜던시를 추가한다. org.springframework.boot spring-boot-starter-validation DTO 에 validation 추가 이전 포스팅의 MemberDto 에 validation 을 추가한다. package com.example.spring.docs.example.dto; import jakarta.validation.constraints.Max; i..

Spring REST Docs + asciidoctor + restdoc spec + swagger ui 를 통한 문서 자동화를 구현해 보자. 구현 순서는 아래와 같다. 문서화를 위한 디펜던시 추가 및 플러그인 작성 문서화 대상이 되는 컨트롤러 클래스 및 서비스 작성 문서화를 위한 테스트 코드 작성 테스트 코드를 실행하여 Spring REST docs (.adoc) 문서 파일 생성 Html 문서 작성을 위한 asciidoctor template 생성 maven plugin 실행을 통해 Html, OpenApi-v2, OpenApi-v3, postman-collection 문서 생성 swagger ui 디펜던시 추가 및 설정으로 swagger ui 페이지 접속 postman-collection.json 파..

스프링에서 REST API 에 대한 문서화를 진행할 때 보통은 swagger + swagger ui 를 많이 사용하지만 개발코드에 문서화를 위한 annotation 을 지정해야함. API 가 업데이트 되었을 때 실수로 문서화에 대한 코드를 누락하여 실제 API 와 문서간의 동기화가 이루어지지 않을 소지가 있음. 과같은 단점이 있다. 위와 같은 단점을 해결하기 위해서는 스프링에서 제공하는 REST Docs + AsciiDoctor + Restdoc-spec + Swagger UI 를 통해서 개발코드를 오염시키지 않고 테스트 코드 기반으로 문서자동화를 구현할 수 있다. 물론 테스트 코드 기반으로 API 문서를 작성하기 때문에 보다 견고한 API 검증과 함께 문서화를 이룰 수 있는 장점이 있지만 적용하기 쉽지..