Add header parameter in Swagger UI documentation using Springfox

Question

I want to add a header parameter field to the auto-generated documentation for my leisure service. I am using Spring and 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); } 

As you can see, I already have the body parameter. I just want to add a header header .

Answer 1

I just added @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; )

You can also add a global header for each service in your documentation using the solution described here: Spring + Springfox + Header Parameters

Answer 2

I prefer to use @ApiImplicitParam after my @RequestMapping and not as function parameters, because usually you can process your headers in a filter (for example, authentication) and you do not need values ​​in this method.

In addition, if you need them in a method, Swagger auto provides a field for @HeaderParam

This style also improves readability and flexibility when some calls need headers and others don't.

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

If all or most of your endpoints need a headline, I would rather configure it as shown here

If you need to declare several header parameters, you need to use the @ApiImplicitParams annotation:

 @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 3

If you have more header options, then each API will have as many @RequestHeader

To avoid this, and your API looks simple, you can use the HeaderInterceptor to collect header information.

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

Your API will look like this with @RequestAttribute ("headerName")

 public @ResponseBody ResponseEntity<MyResponse> getSomeApi( //Headers common for all the API @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 { .... } 

Your Swagger should still describe all the API headers, for this you can add parameters to the swagger Docket, SwaggerConfig. Note that ignoredParameterTypes, as we mentioned, ignores HeaderVo, as it is internal to the application. swagger does not require to show that

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