[Springdoc] swagger Unable to render this definition 오류 조치

Swagger UI 로 application의 API 정보를 보고 싶은데 Unable to render this definition 오류가 나며 되지 않는다. 

swagger-ui Unable to render this definition

지난번에 기술한 [Springdoc] No mapping for GET /swagger-ui/index.html 오류와 같이 다른 Springdoc api 호출은 잘 된다. UI 쪽만 문제가 있다. 그리고 또 마찬가지로 새로 프로젝트 만들어서 Springdoc을 적용하면 문제 없다. 커스터마이징 된 부분에 문제가 있는듯 하다. 문제에 대해 딱히 오류메세지가 출력되는것이 아니라 문제를 찾기 힘들었다. 

 

원인을 파악하기 위해 새로 프로젝트를 만들어서 Springdoc을 적용시킨 프로젝트와 문제가 있는 프로젝트를 비교했다.

 

잘 되는 프로젝트의 http://localhost:8080/v3/api-docs

{"openapi":"3.0.1","info":{"title":"OpenAPI definition","version":"v0"},"servers": ...

잘 안되는 프로젝트의 http://localhost:8080/v3/api-docs

"{\"openapi\":\"3.0.1\",\"info\":{\"title\":\"OpenAPI definition\",\"version\":\"v0\"},\"servers\":

차이가 보인다. 잘 되는 프로젝트에서는 Json으로 잘 안되는 프로젝트는 String으로 표현이 된다. messageConverter 관련 부분에 문제가 있다고 인식을 하였다. 잘 되는 프로젝트는 모두 Springboot의 기본 설정을 사용하기 때문에 이런 부분들이 잘 맞춰져 있을테지만 잘 안되는 프로젝트는 messageConverter를 커스터마이징을 해 놓았다. 

 

잘 안되는 프로젝트의 messageConverter 설정부

GsonHttpMessageConverter gsonHttpMessageConverter = new GsonHttpMessageConverter();
gsonHttpMessageConverter.setGson(GSON);
messageConverters.add(gsonHttpMessageConverter);
		
StringHttpMessageConverter stringHttpMessageConverter = new StringHttpMessageConverter();
stringHttpMessageConverter.setDefaultCharset(StandardCharsets.UTF_8);
messageConverters.add(stringHttpMessageConverter);

기존에는 messageConverter에 GsonHttpMessageConverter, StringHttpmessageConverter 순서로 add를 해 주었다. 이렇게 추가를 해준다고 해서 리턴되는 값이 String 형식으로 나오고 그런건 아니었는데 swagger-ui 쪽만 이상하게 나온다.

혹시나 하는 마음으로 이 두개의 순서를 바꿔보았다. 

StringHttpMessageConverter stringHttpMessageConverter = new StringHttpMessageConverter();
stringHttpMessageConverter.setDefaultCharset(StandardCharsets.UTF_8);
messageConverters.add(stringHttpMessageConverter);

GsonHttpMessageConverter gsonHttpMessageConverter = new GsonHttpMessageConverter();
gsonHttpMessageConverter.setGson(GSON);
messageConverters.add(gsonHttpMessageConverter);

오류 해결! swagger-ui 가 정상적으로 작동한다. 아마도 마샬링 과정에서 적절하게 처리할 messageConverter를 찾지 못해서 마지막에 설정한 messageConverter로 설정이 되어 이런 문제가 발생했던것 같다. 

 

Unable to render this definition 에 대해 다른 원인들도 있겠지만 적어도 나의 경우는 messageConverter의 설정 문제였다. 

 

끝!