SpringDoc OpenAPI 控制器异常响应文档化的精准控制

在Spring Boot应用开发中，SpringDoc OpenAPI是一个广泛使用的库，用于自动生成API文档。本文将深入探讨一个关于控制器异常响应文档化的常见问题及其解决方案。

问题背景

在Spring MVC应用中，开发者通常会使用@ControllerAdvice配合@ExceptionHandler来集中处理各种异常情况。为了在API文档中准确反映这些异常响应，我们会使用@ApiResponse注解进行标注。

然而，在SpringDoc OpenAPI 2.3.0版本中存在一个文档化问题：当在控制器建议类(ControllerAdvice)中使用@ApiResponse标注异常处理器时，这些异常响应会被错误地应用到所有控制器方法上，即使某些方法根本不会抛出这些异常。

问题示例

考虑以下代码示例：

@RestController
class HelloController {
    @GetMapping("/hello")
    @Operation(operationId = "hello", summary = "Hello, World!")
    fun hello() = HelloResponse("World")

    @GetMapping("/greet/{name}")
    @Operation(operation = "greet", summary = "Hello someone!")
    @Throws(InvalidNameException::class)
    fun greet(@PathVariable name: String) = throw InvalidNameException("Name '$name' is invalid!")
}

@ControllerAdvice
class HelloAdvisor {
    @ExceptionHandler(InvalidNameException::class)
    @ResponseStatus(HttpStatus.BAD_REQUEST)
    @ApiResponse(description = "The provided name is invalid", useReturnScheme = true)
    fun handleNameException(e: InvalidNameException): MyErrorResponse {
        TODO()
    }
}

在这个例子中，InvalidNameException只会在greet方法中被抛出，但SpringDoc却错误地将这个异常响应也添加到了hello方法的API文档中。

技术原理分析

这个问题的根源在于SpringDoc对控制器建议类的处理逻辑。在2.3.0版本中，SpringDoc会扫描所有带有@ApiResponse注解的异常处理器，并将它们应用到所有控制器方法上，而不会考虑这些方法是否真的会抛出这些异常。

这种行为与开发者期望不符，因为：

1. 它会导致API文档不准确，显示了不存在的异常响应
2. 增加了API消费者的理解负担
3. 降低了文档的可信度

解决方案

SpringDoc团队在2.3.1-SNAPSHOT版本中修复了这个问题。修复后的行为是：

• 只有当控制器方法明确声明会抛出某异常（通过@Throws注解或方法签名）时
• 或者当方法确实可能抛出某异常时
• 相应的异常响应才会被包含在该方法的API文档中

最佳实践

基于这个修复，开发者可以：

1. 继续使用@ControllerAdvice集中处理异常
2. 使用@ApiResponse清晰地文档化异常响应
3. 通过@Throws注解或方法签名明确声明方法可能抛出的异常
4. 确保API文档准确反映每个端点真实的异常情况

升级建议

对于遇到此问题的开发者，建议：

1. 升级到SpringDoc OpenAPI 2.3.1或更高版本
2. 重新审视API文档，确保异常响应的准确性
3. 适当添加@Throws注解以提高文档的明确性

这个改进使得SpringDoc生成的API文档更加精确，更好地反映了API的实际行为，提升了开发者体验和API文档的质量。