生产力接口文档工具-Swagger

基本使用

常用注解

@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 名字重复,会导致文档显示错乱