使用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);
}

如你所见，我已经有了一个体型参数。我只想添加一个头类型。

Answer 1

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

此外，如果您在方法中需要它们，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<*>{}

Answer 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);
}

（Qazxswpoi）

您还可以使用此处描述的解决方案在文档中的每个服务上添加全局标头：import org.springframework.web.bind.annotation.RequestHeader;

Answer 3

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

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

Spring + Springfox + Header Parameters

您的API将如下所示，带有@RequestAttribute（“headerName”）

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;
   }

 }

你的Swagger仍然应该描述API的所有标题，因为你可以在swagger中添加参数Docket，SwaggerConfig请注意ignoredParameterTypes，我们提到忽略HeaderVo，因为它是应用程序的内部。昂首阔步并不需要表明这一点

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  {
  ....
 }