[Spring] 스웨거(Swagger) 렌더링이 안 될 때(Unable to render this definition) 체크해볼 것 - messageConverter

배경

아래 스크린샷의 메시지와 함께 스웨거가 렌더링되지 않는 현상이 발생했습니다.

 

내용만 보면 간단한 문제같아 보입니다. OpenAPI 설정에 필요한 버전 정보를 명시해주면 되는 것처럼 보이기 때문입니다. 취합한 정보를 바탕으로 여러 가지 방법을 적용해봤습니다. 그 과정에서 application.properties에 설정값도 넣어보고,  @OpenAPIDefinition 어노테이션을 통해 문서 정보를 기입해보기도 하고, 별도의 SwaggerConfig 클래스를 생성하여 설정을 주입해보기도 하고, 스프링부트 버전과 springdoc의 버전을 변경해보기도 했지만 문제를 해결할 수는 없었습니다. 

문제의 원인

1. 파싱 불가능한 형태로 openapi 명세가 리턴됨

스웨거에서는 왜 버전 필드를  읽어오지 못했을까요?

저의 경우 문서는 생성되었으나 파싱할 수 없는 형태로 openapi명세가 리턴되었기 때문이었습니다. 

 

프로젝트 구동 시 스웨거는 springdoc 의존성이 생성한 openapi 명세를 읽어와 이를 바탕으로 문서를 생성합니다. openapi 명세는 별도의 설정이 없다면 <URL>/api-docs로 호출하여 가져올 수 있는데, 스웨거 문서가 실행되면 아래 스크린샷에서 볼 수 있듯이 내부에서 순차적으로 이 경로를 호출하게 됩니다.

 

그리고 그 형태는 아래와 같은 json형태여야합니다.

 

 

저의 경우 이 리턴 값이 인코딩된 스트림형태로 나타났습니다. 업무망에서 발견한 문제여서 스크린샷을 첨부할 수는 없지만 "eYfbsWxi..." 와 같은 단일 문자열 형태의 응답이 리턴되는 현상을 관찰할 수 있었습니다.

2. 파싱 불가능한 형태로 리턴된 이유

필요에 의해 configureMessageConverters 메서드를 오버라이딩한 것이 원인이었습니다. 이 메서드를 오버라이딩 하여 메시지 컨버터를 커스터마이즈할 경우 별도로 HttpMessageConverter에 ByteArrayHttpMessageConverter를 등록해주는 과정이 있어야 정상적인 형태로 openapi 명세를 얻을 수 있습니다. springdoc 공식 문서에서 해당 내용을 확인할 수 있었습니다.

해결 방법

문제해결은 간단합니다. 오버라이딩한 설정 내부에 아래와 같이 ByteArrayHttpMessageConverter를 등록해줍니다. 가장 처음 순서로 등록해야합니다. 저는 이 조치 이후 정상적으로 json이 리턴되는 것을 확인할 수 있었습니다.

@Override
public void configureMessageConverters(List<HttpMessageConverter<?>> converters) {
    ...
    // 가장 처음 순서로 등록
    converters.add(new ByteArrayHttpMessageConverter());
    ...
}