1. @Api
用于类;表示标识这个类是swagger的资源
tags–表示说明
value–也是说明,可以使用tags替代
Controller1
@Api(value = "demo1测试",tags = "测试Controller1")
@RestController
@RequestMapping("demo/one/controller")
public class DemoOneController {
}
Controller2
@Api(value = "demo2测试",tags = "测试Controller2")
@RestController
@RequestMapping("demo/two/controller")
public class DemoTwoController {
}
效果
2. @ApiOperation
用于方法
value用于方法描述
notes用于提示内容
@ApiOperation(value = "接口的功能简介",notes = "提示接口使用者注意事项")
效果
3. @ApiImplicitParams 与 @ApiImplicitParam
@ApiImplicitParams:用在请求的方法上,表示一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传(默认是false)
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)–> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType=“Integer”
defaultValue:参数的默认值
3.1@ApiImplicitParam单独使用
@ApiOperation(value = "接口的功能简介",notes = "提示接口使用者注意事项")
@ApiImplicitParam(dataType = "string",name = "name",
value = "姓名",required = true,paramType = "path")
@RequestMapping(value = "/demeOne/{name}",method = RequestMethod.GET)
public String demeOne(@PathVariable String name) {
System.out.println(name);
return "hello "+ name;
}
效果
3.2 @ApiImplicitParams 与 @ApiImplicitParam 组合使用
@ApiOperation(value = "接口的功能介绍",notes = "提示接口使用者注意事项")
@ApiImplicitParams({
@ApiImplicitParam(dataType = "string",name = "name",
value = "姓名",required = true,paramType = "path"),
@ApiImplicitParam(dataType = "string",name = "sex",
value = "性别",required = true,paramType = "path"),
@ApiImplicitParam(dataType = "int",name = "age",
value = "年龄",required = true,paramType = "path")
})
@RequestMapping(value = "/demoTwo/{name}/{sex}/{age}",method = RequestMethod.POST)
public String demoTwo(@PathVariable String name,
@PathVariable String sex,
@PathVariable String age) {
System.out.println(name);
System.out.println(sex);
System.out.println(age);
return "hello "+ name;
}
效果
3.3 传递的是pojo类型的参数
controller
@ApiOperation(value = "接口的功能介绍",notes = "提示接口使用者注意事项")
@RequestMapping(value = "/demoThree",method = RequestMethod.POST)
public String demoThree(@RequestBody User user) {
System.out.println(user.getName());
System.out.println(user.getSex());
System.out.println(user.getAge());
return "hello "+ user.getName();
}
pojo实体类
@ApiModelProperty(hidden = true)表示不需要在swagger页面进行展示,required表示该属性为必需的属性。
节省空间没写get、set方法
@ApiModel(value = "用户实体类",description = "这是用户对象")
public class User {
//主键
@ApiModelProperty(hidden = true) //不在swagger中显示
private Integer id;
//姓名
@ApiModelProperty(value = "用户名",example = "帅小伙",required = true)
private String name;
//性别
@ApiModelProperty(value = "性别",example = "男/女",required = true)
private String sex;
//年龄
@ApiModelProperty(value = "年龄",example = "20",required = true)
private Integer age;
}
效果
4. @ApiResponses 与 @ApiResponse
@ApiResponses:用于请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
@ApiResponses({
@ApiResponse(code=400,message="请求参数没填好"),
@ApiResponse(code=401,message="没有访问权限"),
@ApiResponse(code=403,message="访问被拒绝"),
@ApiResponse(code=404,message="请求路径没有或页面跳转路径不对"),
@ApiResponse(code=500,message="后台代码报错")
})
效果