이번 글에서는 Spring Swagger를 사용할 때 Response Model이 보이지 않아서 생기는 불편함을 해결했던 방법에 대해서 공유해보려 합니다.
Swagger에서 Response Model이 보이지 않는다는 것은 위와 같은 상황인데요. 위의 Swagger는 제가 개발하고 있는 API 인데, 어떤 응답이 오는지 실행을 해보기 전까지는 어떤 형식으로 응답이 오는지 알 수 없습니다. 그래서 클라이언트 입장에서는 API 마다 실행해본 후에 응답 형식을 확인해야 한다는 단점이 존재했습니다.
그래서 클라이언트가 매번 실행해서 확인하기 힘들어 따로 API 문서를 작성해야 하는 상황이 생겼습니다.(Swagger를 사용할 때의 장점을 활용하지 못하는 상황이,,,)
그래서 제가 원하는 상황은 위의 사진처럼 API 호출을 해보지 않아도 Swagger에 어떤 응답 형식으로 오는지 바로 알 수 있도록 하는 것이 이번 글의 목표입니다. 바로 알아보러 고고싱~!
Swagger에서 Response Model이 보이지 않을 때는 클라이언트에게 Response DTO를 응답으로 내려줄 때 DefaultResponse로 감싸서 보내주고 있습니다.
DefaultResponse 코드의 일부를 보면 내부적으로 Response Body에 데이터를 담기 위해 Map을 사용하고 있고 ResponseEntity가 DefaultResponse를 다시 감싸고 있는 것을 볼 수 있습니다. (ResponseEntity가 무엇인지 모르겠다면?)
즉, 이렇게 ResponseEntity가 ResponseDTO를 바로 사용하면 괜찮은데, 한번 더 감싸고 있는 DefaultResponse를 사용하고 있기 때문에 Swagger에서는 Response Model을 알 수 없기에 나오지 않는 것이었습니다.
제가 말하는 문제를 해결하는 방법은 다양하게 있을 것이라 생각이 됩니다. 왜냐하면 개발하는 프로젝트마다 서버 - 클라이언트 사이에 어떤 통신 규격으로 개발할지 조금씩 차이가 있을 수 있기 때문입니다. 예를들어 어떤 프로젝트는 Response Body에 HTTP Status Code를 넣어서 보내는 곳도 있고, 어떤 곳은 Response Body에 넣지 않고 Response Header에 존재하는 것을 사용하는 것처럼 차이가 있을 것입니다.
그래서 제가 해결하고자 하는 방법은 ResponseEntity를 DefaultResponse를 감싸지 않고 응답을 보내자 입니다.
이번에는 ApiResponse 라는 이름으로 Response DTO를 감싸는 용도로 만들었고, Map을 사용하지 않고 제네릭을 사용하였습니다.
그리고 Controller에서 Response DTO를 한번만 감싼 ApiResponse를 활용해서 바로 응답을 내려주는 식으로 수정하였습니다. (지금은 임시 코드라서 DTO를 직접 생성해서 내려주고 있습니다.)
그리고 Swagger를 실행해서 확인해보면 위와 같이 Response Model이 잘 보이는 것을 볼 수 있습니다. Swagger 사용법을 모르겠다면?
이번 글의 코드가 궁금하다면 Github 에서 확인하실 수 있습니다.