使用 springdoc-openapi 为 spring Rest Api 显示响应代码的多个描述

Question

我正在使用 java spring 引导框架处理 rest api，我尝试使用springdoc-openapi生成端点文档，我按照本教程制作了文档，唯一的问题是当我尝试为同一个 Http 错误设置多个描述时代码（如下面的 404）只有第一个显示在生成的文档中。

@ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Task updated successfully",
                    content = {@Content(mediaType = "application/json",
                            schema = @Schema(implementation = Task.class))}),
            @ApiResponse(responseCode = "400", description = "Friend email equal to user email",
                    content = @Content),
            @ApiResponse(responseCode = "401", description = "Invalid Id Token",
                    content = @Content),
            @ApiResponse(responseCode = "404", description = "Friend not found",
                    content = @Content),
            @ApiResponse(responseCode = "404", description = "Friend email is null",
                    content = @Content),
            @ApiResponse(responseCode = "404", description = "Task not found",
                    content = @Content)})

结果如下图： \

是否可以为相同的响应代码定义多个descriptions （不是@Schema ）？ （我已经搜索过，但到目前为止我只找到了如何设置多个模式）

Answer 1

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#responsesObject声明 Responses object 包含Any HTTP status code can be used as the property name, but only one property per code - 这意味着您不能在结果 swagger 中重复状态代码，一个状态代码 = 一个响应 object。同样，它在响应 object 中定义了一个description字段。

因此，您的问题不在于 springdoc，而在于 OpenAPI 规范——在您尝试生成的文档的规范中不允许出现“对同一 HTTP 错误代码的多个描述”这样的事情。

通常，当使用生成规范的工具遇到问题时，请尝试手动编写您的想法并从那里向后工作。

Answer 2

您正在尝试使用注释@ApiResponse在声明性级别为同一错误代码设置不同的响应我不知道该注释，但它如何区分同一响应代码的不同错误？ 无论如何，我可以为您提供一个解决方案，如何使用您自己的代码来做到这一点。 您可以使用ResponseEntity class 并在基于您自己的业务逻辑的代码中，您可以提供您选择的错误代码和自定义错误消息。 这意味着根据您自己的逻辑，您可以提供具有不同错误消息的相同错误代码。 有关详细信息，请参阅使用 Spring ResponseEntity 操作 HTTP 响应文章。 还有另一种以更一般的方式处理错误的方法。 有关详细信息，请参阅此问题