[SpringBoot] Swagger 사용할때 반드시 주의할 점!! - @ApiModel 의 value는 겹치면 안된다.

오늘 모처럼 빨간날이라 쉬던 와중에 같은 팀원으로부터 api 에 전달해야할 정보가 뭔가 이상하다는 카톡을 받았다. 

급히 swagger api spec 에 접속해서 확인해보니 정말 뭔가 이상했다. api 명세를 보니 Dto 객체를 전달받아서 그 Dto 를 통해서 이것저것 작업을 수행해줘야 하는데 어째 api spec 에 명시된 필드들이 Dto에 있는 필드들보다 더 많은 필드들이 존재했다. 이 Dto에서는 이런 필드를 정의해준적이 없는데 어디서 나온 필드들일까? 하고 생각했다. 

 

그런데 그 필드들은 어디선가 많이 본듯한 필드인 것을 직감했다. 

 

먼저 결론부터 말하겠다. Swagger 어노테이션을 사용하면서 @ApiModel 라는 어노테이션에 해당 네임을 적어주는 기능이 존재한다. 그런데 만약 다른 도메인 객체 혹은 서로 다른 Dto 에서 어딘가 @ApiModel 에 명시된 네임과 동일한 네임을 갖고 있다면 어떻게 될까? 정답은 두개의 객체의 필드가 혼합되어서 나타난다. 이게 문제의 원인이었다. 

 

자 아래 두개의 사진이 보일 것이다. 첫번째는 Dto 이고 두번째는 Domain 객체이다. (지금은 수정된 상태) @ApiModel 에 주목해라. 

Dto

 

도메인

지금 두개의 사진을 보면 @ApiModel 이 맨 처음 어노테이션으로 명시된 것이 보일 것이다. 지금은 Dto 에서는value = "댓글" 이라고 되어있고 도메인 객체(두번째 사진)에서는 value="댓글 도메인 객체" 라고 된 것이 보일 것이다. 이건 내가 수정해줬기 때문에 즉 이렇게 바꿔놨기 때문에 문제가 없는 상황이다. 그런데 만약 두 값을 동일하게 모두 value="댓글" 이라고 선언한다면? 두 개의 대상에서 똑같은 name 을 가지고 있다? 그러면 이 두 객체에 존재하는 모든 필드들이 혼합되어서 Swagger api spec 에 등장한다는 소리다. 즉 opponentId, content, id, userId 가 모두 혼합되어서 등장한다. 

 

그러니 무심코 @ApiModel 의 value 를 겹쳐서 주진 말자. 이건 에러로그도 뜨지 않고 어떤 이상징후도 감지할 수 없는 문제다. 즉 클라이언트가 직접 고생해가면서 코드를 짜다가 중간에서야 뭔가 이상함을 느껴야만 감지되는 오류다. (오류라기 보다는 문제) 아니면 내가 직접 swagger api spec 을 보다가 내가 정의한 객체의 필드에 뭐가 있었는지 기억하면서도 그 api spec에서 뭔가 다른점을 인지해야만 알 수 있는 문제다. 명심합시다. (근데 Swagger를 쓴 이상 api 스펙 자동화를 통해 좀 편하게 개발하자는건데 이걸 택한 사람이 api 필드들을 전부 체크해가면서 이상은 없는지 다 체크할 사람은 아닐테니 그만큼 발견하기 힘든 문제가 될거다. 진작 그렇게 꼼꼼하게 체크할 사람이었으면 Swagger 가 아니라 spring rest doc 을 썼을거다. )

 

아래는 이제서야 제대로 명시된 Swagger api spec 이다. 휴 휴