注键说明
maven依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.6</version>
</dependency>
注键整体说明
作用于controller类上:
注键 | 说明 |
---|---|
@Api | 对请求类的说明 |
@Api
: 请求类说明
@Api:放在请求的类上,与 @Controller 并列,说明类的作用,如用户模块,订单类等。
参数说明:
tags="说明该类的作用"
value="该参数没什么意义,所以不需要配置"
示例:
@RestController
@RequestMapping("/user")
@Api(tags="用户注册相关接口")
@AllArgsConstructor
public class UserRegisterController {
// controller层代码
}
@Api
其它属性配置
属性名称 | 备注 |
---|---|
value | url的路劲值 |
tags | 设置该值,value的值便会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径 |
position | 配置多个Api 想改变显示的顺序位置 |
produces | 如, “application/json, application/xml” |
consumes | 如, “application/json, application/xml” |
protocols | 协议类型,如: http, https, ws, wss |
authorizations | 高级特性认证时配置 |
hidden | 配置为true ,将在文档中隐藏 |
作用于类上(对象类):
注键 | 说明 |
---|---|
@ApiModel | 用在JavaBean类上,说明JavaBean的 用途 |
@ApiModelProperty | 用在JavaBean类的属性上面,说明此属性的的含议 |
@ApiModel
: 作用于JavaBean,表示对JavaBean的功能的描述
- 当请求数据描述时(即
@RequestBody
时),用于封装请求(包括数据的各种校验)数据 - 当响应值是对象时(即
@responseBody
时),用于返回值对象的描述
@ApiModelProperty
: 作用于JavaBean类的属性上,说明属性的含义
实体类
@Data
@ApiModel(value= "发送验证码参数")
public class CheckRegisterSmsParam {
@ApiModelProperty(value = "手机号")
@Pattern(regexp= PrincipalUtil.MOBILE_REGEXP,message = "请输入正确的手机号")
private String mobile;
@ApiModelProperty(value = "验证码")
private String validCode;
}
controller层
@RestController
@RequestMapping("/user")
@Api(tags="用户注册相关接口")
@AllArgsConstructor
public class UserRegisterController {
@PutMapping("/checkRegisterSms")
@ApiOperation(value="校验验证码", notes="校验验证码返回校验成功的标识")
public ResponseEntity<String> register(@Valid @RequestBody CheckRegisterSmsParam checkRegisterSmsParam) {
// 每个ip每分钟只能发十个注册的验证码,免得接口被利用
if (!smsLogService.checkValidCode(checkRegisterSmsParam.getMobile(), checkRegisterSmsParam.getValidCode(), SmsType.REGISTER)){
throw new YamiShopBindException("验证码有误或已过期");
}
String checkRegisterSmsFlag = IdUtil.simpleUUID();
RedisUtil.set(CHECK_REGISTER_SMS_FLAG + checkRegisterSmsFlag, checkRegisterSmsParam.getMobile(), 600);
return ResponseEntity.ok(checkRegisterSmsFlag);
}
}
作用于方法上(请求参数的说明):
注键 | 说明 |
---|---|
@ApiOperation | 方法的说明 |
@ApiImplicitParams、@ApiImplicitParam | 方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明 |
@ApiOperation
: 作用于方法上, 对方法进行说明
@ApiOperation:"用在请求的方法上,说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
@ApiImplicitParams
、@ApiImplicitParam
:作用于方法上,方法参数的说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:对单个参数的说明
name:参数名
value:参数的说明、描述
required:参数是否必须必填
paramType:参数放在哪个地方
· query --> 请求参数的获取:@RequestParam
· header --> 请求参数的获取:@RequestHeader
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(请求体)--> @RequestBody User user
· form(普通表单提交)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
示例:
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation(value="用户登录",notes="随便说点啥")
@ApiImplicitParams({
@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
})
@PostMapping("/login")
public JsonResult login(@RequestParam String mobile, @RequestParam String password,
@RequestParam Integer age){
//...
return JsonResult.ok(map);
}
}
作用于方法上(返回参数的说明):
注键 | 说明 |
---|---|
@ApiResponses、@ApiResponse | 方法返回值的说明 ;@ApiResponses 用于指定单个参数的说明 |
@ApiResponses
、@ApiResponse
:作用于方法上,方法返回值的状态码说明
@ApiResponses:方法返回对象的说明
@ApiResponse:每个参数的说明
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
示例:
@Api(tags="用户模块")
@Controller
public class UserController {
@ApiOperation("获取用户信息")
@ApiImplicitParams({
@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
})
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ResponseBody
@RequestMapping("/list")
public JsonResult list(@RequestParam String userId) {
...
return JsonResult.ok().put("page", pageUtil);
}
}