spring - 如何在 springdoc Schema 中描述标准的 Spring 错误响应？

Question

如果出现未处理的错误，SpringBoot 应用程序的默认服务器响应是

{
    "timestamp": 1594232435849,
    "path": "/my/path",
    "status": 500,
    "error": "Internal Server Error",
    "message": "this request is failed because of ...",
    "requestId": "ba5058f3-4"
}

我想在应用程序路由的 Springdoc 注释中描述它。

假设有一个标准类 DefaultErrorResponse(只是一个模拟名称)，它可能如下所示:

@Operation(
  // ... other details
  responses = {
    // ... other possible responses
    @ApiResponse(
      responseCode = "500",
      content = @Content(schema = @Schema(implementation = DefaultErrorResponse.class)))
  }
)

在更糟糕的情况下，这样的类不存在，Spring 仅使用一个 Map 来创建此响应。然后这个注释会更加冗长，包括明确提及响应中包含的每个字段。

显然对于大多数路由来说，这部分 @ApiResponse(responseCode="500",... 是相同的，减少重复会很好。

在文档中引入默认错误响应描述的正确方法是什么？

Answer 1

对于错误处理，您可以结合使用@RestControllerAdvice 和@ExceptionHandler，以重构错误处理。

springdoc-openapi 会自动扫描这些 spring 注解。无需添加任何额外的 swagger 注释。