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

我想在我的 Rest 服务的自动生成的 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);
}

如你所见，我已经有一个body类型参数。我只想添加一个header输入一。

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

此外，如果您在方法 Swagger auto 中需要它们，则会提供以下字段：@HeaderParam

当某些调用需要标头而其他调用不需要标头时，这种样式还可以提高可读性和灵活性。

Example

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

如果您的端点的全部或大部分需要标头，我宁愿将其配置为所见here https://stackoverflow.com/a/36613259/3307037

如果必须声明多个标头参数，则需要使用@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<*>{}