Swagger3/OpenAPI如何为同一HTTP状态码配置多个响应描述

Swagger 3（基于OpenAPI 3规范实现）不支持为同一个HTTP状态码定义多条独立的响应配置。

OpenAPI 规范本身对接口响应的定义采用「HTTP状态码为唯一键」的映射结构，同一个状态码只能对应一份响应元数据（描述、响应体结构等）。你在@ApiResponses中重复声明两个responseCode = "400"的@ApiResponse时，框架扫描解析阶段会发生配置覆盖，最终仅会保留最后加载的一条400配置，无法同时展示两条独立说明。

将同一状态码下的所有响应场景，合并到同一条@ApiResponse的description字段中，通过换行、列表拆分不同场景的说明即可，Swagger UI 可以正常渲染多行、列表格式的描述内容。
如果两个场景返回的响应体结构存在差异，也可以在同一条@ApiResponse的content中配置多个媒体类型/结构，搭配描述说明对应场景即可。
修改后的示例代码如下：

@ApiResponses(value = {
        @ApiResponse(responseCode = "200", description = "更新成功，返回学生完整信息",
                content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
                        schema = @Schema(implementation = StudentFullDTO.class))}),
        @ApiResponse(responseCode = "400", description = """
                请求参数非法，包含两类常见场景：
                1. 请求体字段未通过校验规则，返回标准异常响应对象ExceptionResponseObject
                2. 传入的待更新字段属于系统禁止修改的字段，返回操作失败提示
                """,
                content = @Content)
})
@PatchMapping("/{id}")
public ResponseEntity<StudentFullDTO> patch(@PathVariable String id,
                                            @RequestBody @Valid Map<Object, Object> fields) {
    StudentEntity studentEntity = studentEntityService.patchStudentEntity(id, fields);
    StudentFullDTO studentFullDTO = modelMapperService.mapObjectToObjectOfEnteredClass(studentEntity, StudentFullDTO.class);
    return new ResponseEntity<>(studentFullDTO, HttpStatus.OK);
}

注：如果项目使用JDK 15以下版本不支持文本块语法，直接用<br/>标签或\n拼接字符串实现换行即可，Swagger UI可正常解析。

内容的提问来源于stack exchange，提问作者Lulex97