API 문서를 제공하는 여러가지 방법 중 Spring REST Docs를 활용하여 문서를 생성하고 제공한 방법이다.
Spring REST Docs를 진행하는 자세한 방법들은 참고자료의 링크들을 참고하고, 현 포스팅에서는 간단한 사용법과 발생한 문제 및 해결법들을 다룬다.
사내 코드의 문제점 등으로 보통 활용하는 @WebMvcTest를 사용하지 않고 @SpringBootTest를 사용하며 변경된 내용들이 있으니 기본적인 활용법으로는 참고하지 않기를 바란다.
진행 내용
@SpringBootTest // 통합 테스트를 위한 Annotation
@AutoConfigureMockMvc // MockMvc 설정을 위한 Annotation
@AutoConfigureRestDocs // RestDocs 설정을 위한 Annotation
@Transactional // DB Rollback을 위한 Annotation
@ActiveProfiles("local") // Local Test를 위한 Annotation
class ControllerTest {}document() 내의 사용법
- requestParam
requestParameters(parameterWithName())사용
- requestHeader
requestHeaders(headerWithName())사용
- requestBody
requestFields(fieldWithPath())사용
- pathParameter
pathParameters(parameterWithName())사용
- response
- request만 response로 변경하여 사용
- details (하위에 많은 항목을 하나의 subject로 묶고싶은 경우)
subsectionWithPath()사용
문제 및 해결
Response의 한글 인코딩이 깨지는 문제
mockMvc.perform 내에서 accept()에 MediaType.APPLICATION_JSON_UTF8을 지정하였는데 Deprecated된 타입이였다. 관련링크
이 부분을 해결하기 위해 mockMvcBuilders의 addFilters를 활용. 활용하자 @AutoConfigureRestDocs의 Configuration을 가져오지 못하는 문제가 발생하여 Configuration을 사용하지 않고 prettyPrint() 등의 PreProcessor를 테스트마다 직접 명시했다.
urlTemplate Not Found Error
REST Docs 작성 중 pathParameter 사용시 상기 에러가 발생했다. 관련링크
mockMvc의 get()을 RestDocumentationRequestBuilders.get()으로 수정하여 해결했다.
File Download의 Response 처리
파일 다운로드 API의 경우 Response로 ZIP 파일이 넘어왔다.
REST Docs 작성으로는 preProcessorResponse()를 활용해서 해당 요청의 Body값을 전부 제거했다.
preProcessorResponse는 responseFields와 같은 Snippet들보다 먼저와야한다. (document 생성자가 그렇게 구현되어 있다.)
Multipart 요청을 처리하는 방법
mockMvc의 file()을 여러번해서 파일과 다른 Form 데이터들을 보내야 한다.
근데, Part가 갈리기때문에 모든 값들을 Part로 각각 전송해야 한다. (MockPart 활용)
REST Docs 에서는 requestParts()에 partWithName으로 값들을 전부 명시한다. (File도)
그리고 RestDocumentationRequestBuilders에는 multipart가 없기에 fileUpload를 활용한다.
이후 변경
이 부분이 가장 중요하게 다루고 싶은 내용인데,
위의 방법은 @SpringBootTest로 진행하다보니 Spring Context를 전부 띄우게되고, 그러다보니 의존하고 있는 다른 라이브러리들을 전부 띄워야하기 때문에 빌드에 시간도 오래 걸리고, 다른 라이브러리들에 대한 의존성이 테스트코드에서도 나타나게 된다.
그래서 @SpringBootTest와 같은 통합테스트가 아닌 단위테스트로 변경하고자 하였고, @WebMvcTest로 진행하고자 했으나 Redis 등의 Config들을 불러오지 못해서 빌드가 안되는 문제가 발생했다.
그래서 Spring Context를 띄우지 않는 MockitoExtension만 활용하는 단위테스트로 변경했고, 이에 대한 내용을 다음 포스팅에 다룰 예정이다.
참고자료
