如何在openApi / springfox-swagger2

Question

给出以下带有springfox-swagger2注释的REST方法：

@GetMapping(value = "/access", produces = MediaType.APPLICATION_JSON_VALUE)
@ApiOperation(value = "check access allowed")
@ApiResponses({
        @ApiResponse(code = 200, message = "okay, there you go", response = AccessResponse.class),
        @ApiResponse(code = 204, message = "I got nothing for you", response = Void.class)
})
public ResponseEntity<AccessResponse> access() {

    if (!isAccessEnabled()) {
        return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
    }
    AccessResponse response = new AccessResponse("some data");
    return ResponseEntity.ok(response);
}

请注意，此方法可以返回两种状态：

1. 类型为AccessResponse的响应
2. http 204-无内容响应

我想生成一个反映不同响应模型（AccessResponse与Void）的详尽的api文档。在@ApiResponse注释中，我明确地告诉springfox-swagger2为每个状态使用不同的模型。 不幸的是，生成的swagger api doc json文件仅引用http 200和204的AccessResponse模型：

"responses":{
  "200":{
    "description":"okay, there you go",
    "schema":{"$ref":"#/definitions/AccessResponse"}
    },
  "204":{
    "description":"I got nothing for you",
    "schema":{"$ref":"#/definitions/AccessResponse"}
    }
}

我想念什么吗？有没有办法告诉swagger为每个HTTP / ok状态代码呈现两个不同的模型？

Answer 1

我更改了方法的返回类型-删除了通用类型：

public ResponseEntity access()

这会带来更好的（但不是完美的）模型描述：

"204":{
   "description": "I got nothing for you",
   "schema":{"type":"object"}
}

Swagger UI将此呈现为

我喜欢它现在显示空的身体。但是，statusCode有点烦人。