如何在Springfox Swagger中删除操作的响应主体？

Question

我正在使用 spring-boot 制作的 REST 服务，该服务至今已使用 springfox-swagger2:2.7.0 （首先实现）进行记录。我添加的最后一个操作如下所示：

@ApiOperation(value = "whatever")
  @ApiResponses({
    @ApiResponse(code = HttpURLConnection.HTTP_NO_CONTENT, message = "Returns empty content when succeeds"),
    @ApiResponse(code = HttpURLConnection.HTTP_FORBIDDEN, message = "You can't do that.")
  })
@CrossOrigin
@PreAuthorize("hasAuthority('USER_ACCESS')")
@RequestMapping(value = "/foo", method = POST, consumes = APPLICATION_JSON_VALUE)
@ResponseStatus(HttpStatus.NO_CONTENT)
public ResponseEntity postFoo(
  @RequestBody
  FooRequestBody requestBody) {

  if (someMethodReturnsTrue()) {
    return ResponseEntity.status(HttpStatus.NO_CONTENT).build();
  } else {
    return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
  }
}

现在的问题是，无论如何，生成的 Swagger 定义最终看起来像这样：

"responses": {
  "204": {
    "description": "Returns empty content when succeeds",
    "schema": {
      "$ref": "#/definitions/ResponseEntity"
    }
  },
  "403": {
    "description": "You can't do that."
  }
}

如果此操作不返回任何内容，我理解“204”响应应该没有

schema

字段（与其他字段一样）。

我尝试在

response = Void.class

注释中指定

@ApiParam

（如其他线程中的建议），但没有任何喜悦（因为它是默认值，所以与不指定它没有区别）。

我还尝试在我的

genericModelSubstitutes(ResponseEntity.class)

bean 中设置

Docket

但没有任何作用。

我知道我可以返回

ResponseEntity

并抛出异常，以防

void

确实返回

someMethodReturnsTrue()

，而不是返回

false

。然后，

@ExceptionHandler

方法可以将该异常转换为 403 状态代码。

我认为这太过分了，我认为我不应该改变我的实现来修复我的文档。这就是为什么我问，有没有办法告诉Springfox忽略该特定方法的返回值并将其视为返回值

void

？

谢谢。

Answer 1

找到解决方法， 由于@ApiOperation的默认行为是返回方法的返回类型，因此对于每个状态，都会返回方法的返回类型。 如果您想发送空回复，请写

@ApiResponse(code = 204, message = "No User found for that Id",response = Object.class)

并在SwaggerConfig中写入

 @Bean
    public Docket productApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .directModelSubstitute(Object.class, java.lang.Void.class);          
    }

因此，每当返回 Object.class 时，swagger 都会自动将其转换为 Void.class

Answer 2

添加：

@ApiResponse(code = 204, response = void.class, message = "No Content")

您的

@ApiResponses({ ... })

注释。重要的是使用

void.class

而不是

Void.class

。因此它与默认值不同，您仍然可以使用

ResponseEntity

作为返回类型。

Answer 3

迁移到 Swagger 3 (OpenAPI 3) 后，情况发生了一些变化。

您可以使用

response = void.class

代替

content = {@Content(examples = {})}

。可能还有其他方法，但这个方法已经足够好了。