spring - 使用 Springfox 在 Swagger UI 文档中添加 header 参数

Question

我想在我的休息服务的自动生成的 swagger ui 文档中添加一个 header 参数字段。我使用 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);
}

如你所见，我已经有一个 正文 类型参数。我只想添加一个 标题键入一。

Answer 1

我更喜欢使用 @ApiImplicitParam在我的 @RequestMapping 之后而不是作为函数参数，因为通常您可能会在过滤器(例如身份验证)中处理您的 header ，并且您不需要该方法中的值。
此外，如果您在方法 Swagger auto 中需要它们，则为 @HeaderParam 提供字段。
当某些调用需要 header 而其他调用不需要时，这种样式还提高了可读性和灵活性。
例子

@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<*>{}

如果您的端点的全部或大部分需要 header ，我宁愿将其配置为 here
如果必须声明多个头参数，则需要使用 @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<*>{}