使用 Springfox 在 Swagger UI 文档中添加一个 header 参数
Add a header parameter in Swagger UI documentation with Springfox
我想在我的休息服务的 auto-generated 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);
}
如您所见,我已经有一个 body 类型参数。我只想添加一个 header 类型。
我刚刚添加了 @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;
)
您还可以使用此处描述的解决方案在文档中的每个服务上添加全局 header:Spring + Springfox + Header Parameters
如果您有更多 header 个参数,那么每个 API 都会有那么多 @RequestHeader
为了避免这种情况并且您的 API 看起来很简单,您可以使用 HeaderInterceptor 来捕获 header 信息。
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 的所有 header,为此您可以在 swagger Docket、SwaggerConfig 中添加参数
请注意 ignoredParameterTypes,我们提到要忽略 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);
}
我更喜欢在我的 @RequestMapping
之后使用 @ApiImplicitParam
而不是作为函数参数,因为通常您可能会在过滤器(例如身份验证)中处理您的 header 而您不需要该方法中的值。
此外,如果您在方法中需要它们,Swagger 会自动为 @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
配置它
如果你必须声明几个header参数,你需要使用@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<*>{}
我想在我的休息服务的 auto-generated 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);
}
如您所见,我已经有一个 body 类型参数。我只想添加一个 header 类型。
我刚刚添加了 @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;
)
您还可以使用此处描述的解决方案在文档中的每个服务上添加全局 header:Spring + Springfox + Header Parameters
如果您有更多 header 个参数,那么每个 API 都会有那么多 @RequestHeader
为了避免这种情况并且您的 API 看起来很简单,您可以使用 HeaderInterceptor 来捕获 header 信息。
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 的所有 header,为此您可以在 swagger Docket、SwaggerConfig 中添加参数 请注意 ignoredParameterTypes,我们提到要忽略 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);
}
我更喜欢在我的 @RequestMapping
之后使用 @ApiImplicitParam
而不是作为函数参数,因为通常您可能会在过滤器(例如身份验证)中处理您的 header 而您不需要该方法中的值。
此外,如果您在方法中需要它们,Swagger 会自动为 @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
配置它如果你必须声明几个header参数,你需要使用@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<*>{}