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

Posted 2023-02-27

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

【英文标题】：Add a header parameter in Swagger UI documentation with Springfox

【发布时间】：2017-04-09 15:29:22

【问题描述】：

我想在我的 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 类型参数。我只想添加一个标题类型。

【参考方案1】：

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

此外，如果您在 Swagger auto 为 @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<*>

如果您的端点的全部或大部分都需要标头，我宁愿按照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<*>

【参考方案2】：

我刚刚添加了@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

【参考方案3】：

如果你有更多的标头参数，那么每个 API 都会有那么多 @RequestHeader

为了避免这种情况并且您的 API 看起来很简单，您可以使用 HeaderInterceptor 来捕获标头信息。

In preHandle() ,  you need to extract the headerInfo in to a an Object and set it as RequestAttribute

  public class MyHeaderInterceptor extends HandlerInterceptorAdapter 

  @Override
  public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler)
        throws Exception  

    HeaderVo headerVo = HeaderVo.createReqHeaderinput(
            request.getHeader("authorization"),
            request.getHeader("contentType"),                
            request.getHeader("myHeaderParam0"),
            request.getHeader("myHeaderParam1"), 
            request.getHeader("myHeaderParam3"),
            request.getHeader("myHeaderParam4"),
            request.getHeader("myHeaderParam5")

            );

     // You can do any validation of any headerInfo here.
     validateHeader(headerVo);

     request.setAttribute("headerName", headerVo);
     return true;
   

 

您的 API 将如下所示，带有 @RequestAttribute("headerName")

public @ResponseBody
ResponseEntity<MyResponse> getSomeApi(
        //Headers common for all the API's       

        @RequestAttribute("headerName") HeaderVo header ,
        @ApiParam(value = "otherAPiParam", required = true, defaultValue = "") 
        @PathVariable(value = "otherAPiParam") String otherAPiParam,
        @ApiParam(value = "otherAPiParam1", required = true, defaultValue = "") 
        @RequestParam(value = "otherAPiParam1") String otherAPiParam1,
        @ApiParam(value = "otherAPiParam2, required = true, defaultValue = "")
        @RequestParam(value = "otherAPiParam2") String otherAPiParam2
     ) throws MyExcp  
  ....
 

您的 Swagger 仍应描述 API 的所有标头，因为您可以在 swagger Docket、SwaggerConfig 中添加参数 请注意ignoreParameterTypes，我们提到忽略HeaderVo，因为这是应用程序内部的。大摇大摆不需要表明这一点

@Bean
public Docket postsApi() 

    //Adding Header
    ParameterBuilder aParameterBuilder = new ParameterBuilder();
    List<Parameter> aParameters = new ArrayList<Parameter>();

    aParameters.clear();

    aParameterBuilder.name("myHeaderParam0").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    aParameters.add(aParameterBuilder.build());
    aParameterBuilder.name("myHeaderParam1").modelRef(new ModelRef("string")).parameterType("header").required(false).build();
    aParameters.add(aParameterBuilder.build());
   ....
   ....

    return new Docket(DocumentationType.SWAGGER_2).groupName("public-api")
            .apiInfo(apiInfo()).select().paths(postPaths()).build().ignoredParameterTypes(HeaderVo.class).globalOperationParameters(aParameters);