[오류해결] Swagger v3 Could not resolve reference: undefined No message available

 

프로젝트에서 API 문서 작성을 위해 swagger를 많이 사용할 것이다. 이왕이면 최신 버전을 사용하고자 컨트롤러의 swagger 내용을 다음과 같이 작성하였다.

 

@RestController
@RequiredArgsConstructor
@RequestMapping("/user")
@Api(tags = "유저 API")
public class UserController {

    private final UserRepository userRepository;

    @Operation(summary = "유저 정보 조회", description = "로그인 상태의 유저 정보 조회", responses = {
        @ApiResponse(
            responseCode = "400",
            description = "만료된 엑세스 토큰이 전달된 경우",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = AuthExResponse.class)
            )
        ),
        @ApiResponse(
            responseCode = "500",
            description = "유효하지 않은 JWT 토큰 전달된 경우",
            content = @Content(
                mediaType = "application/json",
                schema = @Schema(implementation = AuthExResponse.class)
            )
        )
    })
    @GetMapping("/me")
    public User getUser(@CurrentUser UserPrincipal currentUser) {
        Optional<User> userOptional = userRepository.findById(currentUser.getUserId());
        return userOptional.orElse(null);
    }
}

[문제 상황]

각 응답 코드에 따라 반환하는 객체를 schema 속성으로 지정해주었다. 참고로 오류 발생 시 반환되는 AuthExResponse 객체는 ReturnValueHandler에 의해 JSON 형태로 변환되어 반환된다.

 

이 경우 다음과 같은 에러 메시지가 뜨면서 swagger 문서에는 응답 코드에 따른 Example Value에 '(no example available)' 이라고 나타난다.

 

[문제 해결]

처음에는 위의 'Could not resolve reference: undefined No message available' 오류 메시지로 구글링을 해보았지만 문제 상황에 딱 맞는 해결방법을 찾을 수 없었다. 그렇게 몇 분을 해매다가 swagger에서 OpenAPI json 형식 설명을 보여주는 /v3/api-docs에 들어가보니 다음과 같은 오류 메시지가 나타났다.

"responses": {
  "200": {
    "description": "OK",
    "content":{ 
      "*/*": {
        "schema": {
           "$ref": "#/components/schemas/User"
        }
      }
    }
  },
  "400": { 
    "description": "만료된 엑세스 토큰이 전달된 경우",
    "content": {
      "application/json": {
        "schema": { 
          "$ref": "Error-ModelName{namespace='com.project.sooktoring.auth.dto', name='AuthExResponse'}"
        }
      }
    }
  },
  "500": { 
    "description": "유효하지 않은 JWT 토큰 전달된 경우",
    "content": {
      "application/json": {
        "schema": {
          "$ref":"Error-ModelName{namespace='com.project.sooktoring.auth.dto', name='AuthExResponse'}"
        }
      }
    }
  }
}

아마 AuthExResponse의 스키마 모델이 생성되지 않은 것 같은데 다시 "$ref" : "Error-ModelName"으로 구글링을 해보니 다음과 같은 솔루션이 나왔다.

 

@Bean
public Docket api(TypeResolver typeResolver) {
    return new Docket(DocumentationType.OAS_30)
        .additionalModels(
            typeResolver.resolve(AuthExResponse.class)
        )
        .useDefaultResponseMessages(false)
        .select()
        .apis(RequestHandlerSelectors.any())
        .paths(PathSelectors.any())
        .build()
        .apiInfo(apiInfo());
}

바로 .additionalModels(typeResolver.resolve(AuthExResponse.class)) 이 한 줄을 추가하는 것이다.

AuthExResponse 객체가 컨트롤러의 인자나 반환 객체가 아니라 swagger에서 모델 생성을 하지 못하는 것 같아 직접 모델 등록을 해줘야 하지 않나 싶다.

Example Value에 값이 잘 출력된다.

오류해결 끝.