如何在 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

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

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