[TOC] # [@ApiImplicitParams、ApiImplicitParam的使用](https://www.cnblogs.com/h-c-g/p/11004020.html) ## @ApiImplicitParam： 作用在方法上，表示单独的请求参数  参数：  1\. name ：参数名。  2\. value ： 参数的具体意义，作用。  3\. required ： 参数是否必填。  4\. dataType ：参数的数据类型。  5\. paramType ：查询参数类型，这里有几种形式： |类型| 作用 | |--|--| path |以地址的形式提交数据 query| 直接跟参数完成自动映射赋值 body |以流的形式提交 仅支持POST header| 参数在request headers 里边提交 form |以form表单的形式提交 仅支持POST 在这里我被坑过一次：当我发POST请求的时候，当时接受的整个参数，不论我用body还是query，后台都会报Body Missing错误。这个参数和SpringMvc中的@RequestBody冲突，索性我就去掉了paramType，对接口测试并没有影响。 ## @ApiImplicitParams： 用于方法，包含多个 @ApiImplicitParam：  例： ``` @ApiOperation("查询测试") @GetMapping("select") //@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query") @ApiImplicitParams({ @ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"), @ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")}) public void select(){ } ```   效果图：  ## paramType 示例详解 ### path ```java @RequestMapping(value = "/findById1/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION\_JSON\_UTF8\_VALUE) @PathVariable(name = "id") Long id ``` ### body ``` @ApiImplicitParams({ @ApiImplicitParam(paramType = "body", dataType = "MessageParam", name = "param", value = "信息参数", required = true) }) @RequestMapping(value = "/findById3", method = RequestMethod.POST, produces = MediaType.APPLICATION\_JSON\_UTF8\_VALUE, consumes = MediaType.APPLICATION\_JSON\_VALUE) @RequestBody MessageParam param ``` 提交的参数是这个对象的一个json，然后会自动解析到对应的字段上去，也可以通过流的形式接收当前的请求数据，但是这个和上面的接收方式仅能使用一个（用@RequestBody之后流就会关闭了） ### header ``` @ApiImplicitParams({ @ApiImplicitParam(paramType = "header", dataType = "Long", name = "id", value = "信息id", required = true) }) String idstr = request.getHeader("id"); if (StringUtils.isNumeric(idstr)) { id = Long.parseLong(idstr); } ``` ### Form ``` @ApiImplicitParams({ @ApiImplicitParam(paramType = "form", dataType = "Long", name = "id", value = "信息id", required = true) }) @RequestMapping(value = "/findById5", method = RequestMethod.POST, produces = MediaType.APPLICATION\_JSON\_UTF8\_VALUE, consumes = MediaType.APPLICATION\_FORM\_URLENCODED\_VALUE) ``` ## 总结:   - 对于@ApiImplicitParam的paramType：query、form域中的值需要使用@RequestParam获取， header域中的值需要使用@RequestHeader来获取，path域中的值需要使用@PathVariable来获取，body域中的值使用@RequestBody来获取，否则可能出错；而且如果paramType是body，name就不能是body，否则有问题，与官方文档中的“If paramType is "body", the name should be "body"不符。 - @ApiImplicitParams：用在方法上包含一组参数说明 - @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面 - paramType：参数放在哪个地方 : |类型| 作用 |参数值获取| |--|--|--| path |以地址的形式提交数据 |@PathVariable query| 直接跟参数完成自动映射赋值 |@RequestParam body |以流的形式提交 仅支持POST | @RequestBody header| 参数在request headers 里边提交 |@RequestHeader form |以form表单的形式提交 仅支持POST |@RequestParam name：参数名 dataType：参数类型 required：参数是否必须传 value：参数的意思 defaultValue：参数的默认值 @ApiResponses：用于表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如"请求参数没填好" response：抛出异常的类 以上这些就是最常用的几个注解了。 ## 项目例子 ~~~ import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.RequestHeader; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RequestMethod; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import io.swagger.annotations.Api; import io.swagger.annotations.ApiImplicitParam; import io.swagger.annotations.ApiImplicitParams; import io.swagger.annotations.ApiOperation; import io.swagger.annotations.ApiResponse; import io.swagger.annotations.ApiResponses; @RestController @RequestMapping("/user") @Api("userController相关api") public class UserController { @Autowired private UserService userService; @ApiOperation("获取用户信息") @ApiImplicitParams({ @ApiImplicitParam(paramType="header",name="username",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"), @ApiImplicitParam(paramType="query",name="password",dataType="String",required=true,value="用户的密码",defaultValue="wangna") }) @ApiResponses({ @ApiResponse(code=400,message="请求参数没填好"), @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对") }) @RequestMapping(value="/getUser",method=RequestMethod.GET) public User getUser(@RequestHeader("username") String username, @RequestParam("password") String password) { return userService.getUser(username,password); } } ~~~ 测试： 启动服务，浏览器输入"http://localhost:8080/swagger-ui.html"   在上面案例中我们可以知道如果在request域中我们使用reques.getHeader()和使用@RequestHeader注解作用是一样的，其它内容类似。 ~~~ @ApiResponses：用于表示一组响应 @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息 code：数字，例如400 message：信息，例如”请求参数没填好” response：抛出异常的类 ~~~ ~~~ @ApiOperation("获取用户信息") @ApiImplicitParams({@ApiImplicitParam(paramType="header",name="name",dataType="String",required=true,value="用户的姓名",defaultValue="zhaojigang"), @ApiImplicitParam(paramType="query",name="pwd",dataType="String",required=true,value="用户的密码",defaultValue="wangna") }) @ApiResponses({ @ApiResponse(code=400,message="请求参数没填好"), @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对") }) @RequestMapping(value="/getUser",method= RequestMethod.GET) public User getUser(@RequestHeader("name") String name,@RequestParam("pwd") String pwd) { System.out.println(name); System.out.println(pwd); return userRepository.getUserByNameAndPwd(name,pwd); } ~~~