使用 Springfox 在 Swagger UI 文档中添加标头参数

Question

我想在我的休息服务的自动生成的 swagger ui 文档中添加一个标头参数字段。我使用 Spring 和 Springfox。

 public ResponseEntity<User> saveNewUser(
        @ApiParam(value = "the user to create", required = true) @RequestBody User user) throws RestServiceException {

    userService.save(user);
    return new ResponseEntity<User>(user, HttpStatus.OK);
}

如您所见，我已经有了一个 主体 类型参数。我只想添加一个 标题 类型。

原文由 Julien 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 1

我刚刚添加了 @RequestHeader(value="myHeader") String headerStr ：

 public ResponseEntity<User> saveNewUser(
        @RequestHeader(value="myHeader") String headerStr,
        @ApiParam(value = "the user to create", required = true) @RequestBody User user) throws RestServiceException {

    userService.save(user);
    return new ResponseEntity<User>(user, HttpStatus.OK);
}

（ import org.springframework.web.bind.annotation.RequestHeader; ）

您还可以使用此处描述的解决方案在文档中的每个服务上添加全局标头： Spring + Springfox + Header Parameters

原文由 Julien 发布，翻译遵循 CC BY-SA 4.0 许可协议

Answer 2

我更喜欢在我的 --- @ApiImplicitParam @RequestMapping 而不是作为函数参数，因为通常您可能会在过滤器（例如身份验证）中处理标头，并且您不需要该方法中的值。

此外，如果您在 Swagger 自动提供字段的方法中需要它们，则 @HeaderParam

当一些调用需要标头而另一些不需要时，这种风格还提高了可读性和灵活性。

例子

@PostMapping
@ApiImplicitParam(name = "Authorization", value = "Access Token", required = true, allowEmptyValue = false, paramType = "header", dataTypeClass = String::class, example = "Bearer access_token")
fun addJob(jobRequest: Job): ResponseEntity<*>{}

如果您的端点的全部或大部分需要标头，我宁愿按照 此处 所示配置它

如果必须声明多个标头参数，则需要使用 @ApiImplicitParams 注释：

 @PostMapping
@ApiImplicitParams({
  @ApiImplicitParam(name = "Authorization", value = "Access Token", required = true, allowEmptyValue = false, paramType = "header", dataTypeClass = String.class, example = "Bearer access_token"),
  @ApiImplicitParam(name = "X-Custom-Header", value = "A Custom Header", required = true, allowEmptyValue = false, paramType = "header", dataTypeClass = String.class, example = "my header example")
})
fun addJob(jobRequest: Job): ResponseEntity<*>{}

原文由 Enoobong 发布，翻译遵循 CC BY-SA 4.0 许可协议