前言
受新型冠状病毒的影响，在家像猪一样不是睡就是吃，闲着就学着用下Swagger和YApi，特将这几天的学习成果写成了这系列的文章，希望能对大家有所帮助。武汉加油，中国加油！
常用注解汇总：
@Api：用在请求的类上，表示对类的说明
tags="说明该类的作用，可以在UI界面上看到的注解"
value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
@ApiIgnore：用在请求的类或者方法上，表示这个类后者方法被忽略
@ApiOperation：用在请求的方法上，说明方法的用途、作用
value="说明方法的用途、作用"
notes="方法的备注说明"
@ApiParam：用在请求方法中，描述参数信息
name="参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致"
value="参数的简要说明"
defaultValue="参数默认值"
required="属性是否必填，默认为false"
@ApiImplicitParams：用在请求的方法上，表示一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（不常用）
· form（不常用）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值
@ApiResponses：用在请求的方法上，表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：用于响应类上，表示一个返回响应数据的信息
（这种一般用在post创建的时候，使用@RequestBody这样的场景，
请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：用在属性上，描述响应类的属性一、@Api
用在请求的类上，表示对类的说明
常用参数
参数名 | 作用 |
tags | 说明该类的作用，非空时将覆盖value的值 |
value | 描述类的作用 |
其他参数
参数名 | 作用 |
description | 对api资源的描述，在1.5版本后不再支持 |
basePath | 基本路径可以不配置，在1.5版本后不再支持 |
position | 如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持 |
produces | 设置MIME类型列表（output），例：“application/json, application/xml”，默认为空 |
consumes | 设置MIME类型列表（input），例：“application/json, application/xml”，默认为空 |
protocols | 设置特定协议，例：http， https， ws， wss |
authorizations | 获取授权列表（安全声明），如果未设置，则返回一个空的授权值 |
hidden | 默认为false， 配置为true 将在文档中隐藏 |
示例
@Controller
@RequestMapping("/apiDemo")
@Api(tags ="Api注解测试类", value="测试api注解")
public class ApiController {
@RequestMapping(value = "/addtion", method = RequestMethod.GET)
public Object addtion(HttpServletRequest request) {
return null;
}
}
二、@ApiIgnore
用在请求的类或者方法上，表示这个类或者方法被忽略，不会出现在自动生成的Api文档中
示例
@Controller
@RequestMapping("/ignore")
@Api(tags ="ApiIgnore注解测试类", value="测试api注解")
public class IgnoreController {
@RequestMapping(value = "/addtion", method = RequestMethod.GET)
public Object addtion(HttpServletRequest request) {
return null;
}
@ApiIgnore
@RequestMapping(value = "/deletion", method = RequestMethod.GET)
public Object deletion(HttpServletRequest request) {
return null;
}
}
三、@ApiOperation
用在请求的方法上，说明方法的用途、作用
常用参数
参数名 | 作用 |
value | 方法的用户、作用说明 |
notes | 该方法的备注 |
其它参数
参数名 | 作用 |
tags | 操作标签，非空时将覆盖value的值 |
response | 响应类型（即返回对象） |
responseContainer | 声明包装的响应容器（返回对象类型）。有效值为 “List”, “Set” or “Map” |
responseReference | 指定对响应类型的引用。将覆盖任何指定的response（）类 |
httpMethod | 指定HTTP方法，“GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
position | 如果配置多个Api 想改变显示的顺序位置，在1.5版本后不再支持 |
nickname | 第三方工具唯一标识，默认为空 |
produces | 设置MIME类型列表（output），例：“application/json, application/xml”，默认为空 |
consumes | 设置MIME类型列表（input），例：“application/json, application/xml”，默认为空 |
protocols | 设置特定协议，例：http， https， ws， wss |
authorizations | 获取授权列表（安全声明），如果未设置，则返回一个空的授权值 |
hidden | 默认为false， 配置为true 将在文档中隐藏 |
responseHeaders | 响应头列表 |
code | 响应的HTTP状态代码。默认 200 |
extensions | 扩展属性列表数组 |
示例
@Controller
@RequestMapping("/operation")
@Api(tags ="@ApiOperation注解示例类")
public class OperationController {
@RequestMapping(value = "/addtion", method = RequestMethod.GET)
public Object addtion(HttpServletRequest request) {
return null;
}
@RequestMapping(value = "/deletion", method = RequestMethod.GET)
@ApiOperation(value = "测试ApiOperation注解",notes = "swagger注解测试")
public Object deletion(HttpServletRequest request) {
return null;
}
}
四、@ApiParam
用在请求方法的参数中，用于描述参数信息
常用参数
参数名 | 作用 |
name | 参数名称，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致 |
value | 参数的简要说明 |
defaultValue | 参数默认值 |
required | 属性是否必填，默认为false [路径参数必须填] |
其它参数
参数名 | 作用 |
allowableValues | 限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值 |
access | 允许从API文档中过滤参数 |
allowMultiple | 指定参数是否可以通过具有多个事件接受多个值，默认为false |
hidden | 隐藏参数列表中的参数 |
example | 单个示例 |
examples | 参数示例。仅适用于BodyParameters |
示例
@Controller
@RequestMapping("/param")
@Api(tags ="@ApiParam注解示例类")
public class ParamController {
@RequestMapping(value = "/addtion", method = RequestMethod.POST)
@ApiOperation(value = "测试ApiParam注解",notes = "swagger注解测试")
public Object addtion(
@ApiParam(name="account", value="账户名", defaultValue="huzhenv5", required=true) String account,
@ApiParam(name="pwd", value="密码", defaultValue="1111", required=true) String pwd)
{
return null;
}
}
五、@ApiImplicitParam & @ApiImplicitParams
与@ApiParam注解作用相似，用于对方法的参数进行说明，作用比@ApiParam更广泛
@ApiImplicitParam和@ApiImplicitParams均可直接用在请求的方法上，表示一个或者一组参数的说明
@ApiImplicitParams注解可包含一个或多个@ApiImplicitParam注解
@ApiImplicitParam注解可传参数，参数说明如下：
常用参数
参数名 | 作用 |
name | 参数名，参数名称可以覆盖方法参数名称，路径参数必须与方法参数一致 |
value | 参数的汉字说明、解释 |
required | 参数是否必须传，默认为false [路径参数必填] |
paramType | 参数放在哪个地方： header --> 请求参数的获取：@RequestHeader query --> 请求参数的获取：@RequestParam path（用于restful接口）–> 请求参数的获取：@PathVariable body --> 不常用 form --> 不常用 |
dataType | 参数类型，默认String，其它值dataType=“Integer” |
defaultValue | 参数的默认值 |
其它参数
参数名 | 作用 |
allowableValues | 限制参数的可接受值。1.以逗号分隔的列表 2、范围值 3、设置最小值/最大值 |
access | 允许从API文档中过滤参数 |
allowMultiple | 指定参数是否可以通过具有多个事件接受多个值，默认为false |
example | 单个示例 |
examples | 参数示例，仅适用于BodyParameters |
示例
@Controller
@RequestMapping("/implicit")
@Api(tags ="@ApiImplicitParam注解示例类")
public class ImplicitController {
// 一个参数的接口
@RequestMapping(value = "/getDemo10", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value = "乘以10接口",notes = "根据传的参数，返回乘以10的数字")
@ApiImplicitParam(name = "number", value = "被乘数", required = true, paramType = "query", dataType = "int")
public Object getDemo10(HttpServletRequest request) {
Map<String,Object> retMap = new HashMap<String,Object>();
Map<String,String> paramMap = PJCommon.getRequestParamMapAndSessionInfo(request);
try{
int value = 10 * Integer.parseInt(paramMap.get("number").toString());
retMap.put("result", value);
retMap.put("state", 0);
}catch(Exception e) {
e.printStackTrace();
retMap.put("state", 1);
}
return retMap;
}
// 多个参数的接口
@RequestMapping(value = "/getDemoAdd", method = RequestMethod.POST)
@ResponseBody
@ApiOperation(value = "相加接口",notes = "根据传的参数，返回两个数的和")
@ApiImplicitParams({
@ApiImplicitParam(name = "val1", value = "相加数1", required = true, paramType = "query", dataType = "int"),
@ApiImplicitParam(name = "val2", value = "相加数2", required = true, paramType = "query", dataType = "int")
})
public Object getDemoAdd(HttpServletRequest request) {
Map<String,Object> retMap = new HashMap<String,Object>();
Map<String,String> paramMap = PJCommon.getRequestParamMapAndSessionInfo(request);
try{
int value1 = Integer.parseInt(paramMap.get("val1").toString());
int value2 = Integer.parseInt(paramMap.get("val2").toString());
retMap.put("result", value1 + value2);
retMap.put("state", 0);
}catch(Exception e) {
e.printStackTrace();
retMap.put("state", 1);
}
return retMap;
}
}
六、@ApiResponse & @ApiResponses
@ApiResponses用在请求方法上，表示一组响应信息说明
@ApiResponses注解可以包含一个或者多个@ApiResponse注解
@ApiResponse注解直接使用在请求方法上无效
常用参数
参数名 | 作用 |
code | 状态码，例如200、400 |
msg | 状态码对应的信息，例如请求不存在 |
response | 抛出异常的类 |
示例
@Controller
@RequestMapping("/response")
@Api(tags ="@ApiResponse注解示例类")
public class ResponseController {
// 一个参数的接口
@RequestMapping(value = "/addtion", method = RequestMethod.POST)
@ApiResponses({
@ApiResponse(code=400, message="请求参数没填好"),
@ApiResponse(code=404, message="请求路径没有或页面跳转路径不对")
})
public Object addtion(HttpServletRequest request) {
return null;
}
}
七、@ApiModel & @ApiModelProperty
对请求或者响应的类进行说明，@ApiModel和@ApiModelProperty一般配置使用
注意：
- @ApiModelProperty对类的私有属性进行注解时，如果该私有属性没有set或者get方法，则该私有属性在api文档中不会展示
- 当注解的类作为参数时，该参数需要有@RequestBody注解，否则该该参数不会出现在api文档的参数列表中
@ApiModel 常用参数
参数名 | 作用 |
value | 类的说明 |
description | 类的描述 |
@ApiModel 其它参数
参数名 | 作用 |
parent | 为模型提供父类以允许描述继承关系 |
discriminatory | 支持模型继承和多态，使用鉴别器的字段的名称，可以断言需要使用哪个子类型 |
subTypes | 从此模型继承的子类型数组 |
reference | 指定对应类型定义的引用，覆盖指定的任何其他元数据 |
@ApiModelProperty 常用参数
参数名 | 作用 |
value | 属性简要说明 |
name | 运行覆盖属性的名称。重写属性名称 |
@ApiModelProperty 其它参数
参数名 | 作用 |
allowableValues | 限制参数可接收的值，三种方法，固定取值，固定范围 |
access | 过滤属性，参阅:io.swagger.core.filter.SwaggerSpecFilter |
notes | 目前尚未使用 |
dataType | 参数的数据类型，可以是类名或原始数据类型，此值将覆盖从类属性读取的数据类型 |
required | 是否为必传参数,false:非必传参数; true:必传参数 |
position | 允许在模型中显示排序属性 |
hidden | 隐藏模型属性，false:不隐藏; true:隐藏 |
example | 属性的示例值 |
readOnly | 指定模型属性为只读，false:非只读; true:只读 |
reference | 指定对应类型定义的引用，覆盖指定的任何其他元数据 |
allowEmptyValue | 允许传空值，false:不允许传空值; true:允许传空值 |
示例
模型类
@ApiModel(value="user对象", description="登陆用户对象")
public class UserModel {
@ApiModelProperty(value="用户名", name="username", example="huzhenv5")
public String username;
@ApiModelProperty(value="状态", name="state", required=true)
public Integer state;
private String password;
@ApiModelProperty(value="昵称", name="nickName", required=false)
private String nickName;
@ApiModelProperty(value="id数组", name="ids")
public String[] ids;
public String getUsername() {
return username;
}
public void setUsername(String username) {
this.username = username;
}
public Integer getState() {
return state;
}
public void setState(Integer state) {
this.state = state;
}
public String getPassword() {
return password;
}
public void setPassword(String password) {
this.password = password;
}
public String getNickName() {
return nickName;
}
public void setNickName(String nickName) {
this.nickName = nickName;
}
public String[] getIds() {
return ids;
}
public void setIds(String[] ids) {
this.ids = ids;
}
}controller类
@Controller
@RequestMapping("/model")
@Api(tags ="@ApiModel注解示例类")
public class ModelController {
@RequestMapping(value = "/addtion", method = RequestMethod.POST)
@ApiOperation("新增用户")
public UserModel addtion(
@RequestBody @ApiParam(name="用户对象", value="请求时传入json格式", required=true) UserModel user){
return new UserModel();
}
}
