一、类上的定义说明@Api(tages={"类的作用说明"})
例子:
/**
* @Api
* value="不会再界面显示出来"
* tags="说明该类的作用,可以在UI界面上看到的注解,如果tags多个值,会生成多个list"
* @date 2018/7/4 20:17
*/
@Api(tags = {"用户操作接口"})
@Controller
@RequestMapping("/user")
public class UserController {
}
二、方法上的定义说明:有两种方案,分别是 ApiOperation+@ApiImplicitParams+@ApiImplicitParam 和 @ApiOperation+@ApiParam
第一种(推荐,有利于代码阅读):ApiOperation+@ApiImplicitParams+@ApiImplicitParam
@ApiOperation(value = "用于方法描述query",notes = "这是用来说明该方法,提示内容")
@ApiImplicitParams({
@ApiImplicitParam(name = "data",value = "字符串数据",dataType = "String",paramType = "path",example = "白居易",required = true,defaultValue = "白居易"),
@ApiImplicitParam(name = "i",value = "int类型",dataType = "int",paramType = "path",example = "666",required = true,defaultValue = "666")
})
@PostMapping("/query/{data}/{i}")
@ResponseBody
public ResponseCommon query(@PathVariable String data,@PathVariable int i){
return ResponseBuilder.buildSuccessResponse(data + i);
}
@ApiImplicitParams:用在请求的方法上,表示一组参数说明
@ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
第二种:@ApiOperation+@ApiParam
@ApiOperation(value = "用于方法描述",notes = "用于提示内容")
@GetMapping("/{data}")
@ResponseBody
public ResponseCommon string(@ApiParam(name = "data",value = "参数说明",required = true)@PathVariable String data){
return ResponseBuilder.buildSuccessResponse(data);
}
三、实体类的定义说明@ApiModel + @ApiModelProperty
/**
* @author simba@onlying.cn
* @date 2018/7/4 20:18
*/
@ApiModel(value = "用户的POJO",description = "对对象的描述")
public class UserCommon {
@ApiModelProperty(value = "用户Id",name = "userId",dataType = "int",required = true,example = "1",hidden = true)
private int userId;
@ApiModelProperty(value = "用户名",name = "username",dataType = "String",required = true,example = "李白")
private String username;
@ApiModelProperty(value = "用户年龄",name = "age",dataType = "int",required = true,example = "888")
private int age;
@ApiModelProperty(value = "用户密码",name = "password",dataType = "String",required = true,example = "19491001")
private String password;
// getter/setter方法省略
}
四、忽略一个类或者方法的swagger2定义说明:@ApiIgnore
使用该注解忽略这个API,用于类或者方法上