Swagger 3 / OpenApi如何在相同的状态码中添加两个描述

Question

我试图做一些文档我的小api。当状态码400有两种可能的描述时，我该怎么办?我想做一些类似:

@ApiResponses(value = {
@ApiResponse(responseCode = "200", description = "description",
content = {@Content(mediaType = MediaType.APPLICATION_JSON_VALUE,
schema = @Schema(implementation = StudentFullDTO.class))}),
@ApiResponse(responseCode = "400", description = "description" +
"ExceptionResponseObject", content = @Content),
@ApiResponse(responseCode = "400", description = "Odescription",
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);
}

是否可以多次定义相同的状态?

Answer 1

您需要合并这两个描述，并在同一个@ApiResponse(description = "...")注释中指定它们。这是因为OpenAPI规范只允许在每次操作中定义每个HTTP状态码一次。

@ApiResponse(responseCode = "400",
description = "Possible reasons: reason 1; reason 2",
content = @Content),