关于@ApiImplicitParams、ApiImplicitParam的使用说明

关于@ApiImplicitParams、ApiImplicitParam的使⽤说明
⽬录
@ApiImplicitParam
参数
类型作⽤
@ApiImplicitParams
paramType ⽰例详解
⼩结⼀下
测试
@ApiImplicitParam
作⽤在⽅法上，表⽰单独的请求参数
参数
name：参数名。

value：参数的具体意义，作⽤。

required：参数是否必填。

dataType：参数的数据类型。

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
@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)⼩结⼀下
(1)对于@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：参数放在哪个地⽅
header-->请求参数的获取：@RequestHeader
query-->请求参数的获取：@RequestParam
path（⽤于restful接⼝）-->请求参数的获取：@PathVariable
body（不常⽤）
form（不常⽤）
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);
}
以上为个⼈经验，希望能给⼤家⼀个参考，也希望⼤家多多⽀持。