基本使用
常用注解
@Api 描述类/接口的主要用途
@ApiOperation 描述方法用途
@ApiImplicitParam 描述方法的参数
@ApiImplicitParams 描述方法的参数(Multi-Params)
@ApiIgnore 忽略某类/方法/参数的文档
描述类
@Api(tags = "ProtocolApiController" ,description = "协议 管理")
public class ProtocolApiController {
...
}
描述方法
@ApiOperation 描述方法用途
@ApiOperation(value = "查询单个 协议",notes = "备注,可以写很多东西")
@ApiImplicitParam 描述参数
paramType 参数类型,直接写字符串即可
path 路径占位参数
form 表单提交,即formData
query 查询参数
body json格式提交的请求体参数
dataType 数据类型,直接写字符串即可
int 数值
string 字符串
User 对象
List<User> 集合
使用示例
示例1:
@ApiImplicitParams({
@ApiImplicitParam(name = "type", value = "类型", required = false,allowableValues = "1,2,3",paramType = "form" , dataType = "int"),
@ApiImplicitParam(name = "content", value = "内容", required = false ,defaultValue = "1",paramType = "form" , dataType = "String"),
})
@Login
@PutMapping("/update/{id}")
@ApiOperation("修改 协议")
public R update(@PathVariable Long id ,@ApiIgnore ProtocolEntity protocol){
ProtocolEntity dbItem = protocolService.getById(id);
if(dbItem==null){
throw new CustomApiException("ID有误, 未找到对应数据");
}
protocolService.updateById(protocol);
return R.ok();
}
示例2:
@ApiOperation("更新用户")
@ApiImplicitParam(name = "user", value = "单个用户信息", dataType = "User")
@PutMapping("update")
public boolean update(User user) {
return userList.remove(user) && userList.add(user);
}
@ApiOperation("批量删除")
@ApiImplicitParam(name = "users", value = "N个用户信息", dataType = "List<User>")
@DeleteMapping("delete")
public boolean delete(@RequestBody List<User> users) {
return userList.removeAll(users);
}
示例3:
/**
* 修改订单状态
*/
@ApiImplicitParams({
@ApiImplicitParam(name = "id", value = "订单ID", paramType = "form",required = true,dataType = "long"),
@ApiImplicitParam(name = "status", value = "订单状态:300已付款待评价-400已评价-500投诉",allowableValues = "300,400,500" , paramType = "form",required = true,dataType = "long"),
})
@Login
@PostMapping("changeStatus")
@ApiOperation("修改订单状态")
public ApiResponse userChangePhone(Long id,Integer status) {
...
return new ApiResponse<>();
}
示例4:
/**
* 信息
*/
@ApiImplicitParam(name = "taskItemUserId", value = "订单ID", required = true, paramType = "query", dataType = "long")
@GetMapping("/info")
@ApiOperation("查询单个订单的晒图")
public ApiResponse<TaskItemUserImgEntity> info(@RequestParam("taskItemUserId") Long taskItemUserId){
...
return new ApiResponse<>(taskItemUserImg);
}
注意事项
优点:
- 能够解决80%的增删改查接口文档的重复工作量
- 确保前端看到的是最新的文档
缺点:
- Swagger的使用,增加了Controller层和JavaBean的注解工作量
- Response必须层级清晰,否则在Swagger无法自动识别成文档,比如必须写成
Response<PageUtil<ProtocolEntity>>
生产环境禁用Swagger
在SwaggerConfig
类上添加注解,表明生效的环境即可
@Profile("dev")
参考:
https://blog.csdn.net/huo065000/article/details/84944309
Bug
如果多个对象的 @ApiModel
名字重复,会导致文档显示错乱