【Spring Boot】Swagger的常用注解

1. 在Swagger的开发过程中，我们需要在Controller代码等处添加相应的注解，以便可以提高生成的接口文档的可读性
2. 为了解决这些问题，Swagger提供了很多的注解，通过这些注解，我们可以更好更清晰的描述我们的接口，包含接口的请求参数、响应数据、数据模型等信息。其核心的注解主要包含以下信息：

   1. 注解	位置	说明
      @Api	类	加载Controller类上，表示对类的说明
      @ApiModel	类(通常是实体类)	描述实体类的作用
      @ApiModelProperty	属性	描述实体类的属性
      @ApiOperation	方法	说明方法的用途、作用
      @ApiImplicitParams	方法	表示一组参数说明
      @ApiImplicitParam	方法	用在@ApiImplicitParams注解中，指定一个请求参数的各个方面的属性

3. 示例用法
   1. 描述实体类：使用注解@ApiModel、@ApiModelProperty来描述实体类及其类的属性

      1. package com.app.studypro.entity;
         
         import com.baomidou.mybatisplus.annotation.FieldFill;
         import com.baomidou.mybatisplus.annotation.TableField;
         import io.swagger.annotations.ApiModel;
         import io.swagger.annotations.ApiModelProperty;
         import lombok.Data;
         import lombok.experimental.Delegate;
         
         import java.io.Serializable;
         import java.time.LocalDateTime;
         
         /**
          * 用户信息
          *
          * @author Administrator
          */
         @Data
         @ApiModel("用户信息")
         public class User implements Serializable {
         
             private static final long serialVersionUID = 1L;
             /**
              * 主键
              */
             @ApiModelProperty("主键")
             private Long id;
         
             /**
              * 用户名
              */
             @ApiModelProperty("用户名")
             private String username;
         
             /**
              * 密码
              */
             @ApiModelProperty("密码")
             private String password;
         
             /**
              * 性别
              */
             @ApiModelProperty("性别")
             private String sex;
         
             /**
              * 状态 0:禁用，1:正常
              */
             @ApiModelProperty("状态 0:禁用，1:正常")
             private Integer status;
         
             /**
              * 创建时间
              */
             @ApiModelProperty("创建时间")
             @TableField(fill = FieldFill.INSERT)
             private LocalDateTime createTime;
         
             /**
              * 更新时间
              */
             @ApiModelProperty("更新时间")
             @TableField(fill = FieldFill.INSERT_UPDATE)
             private LocalDateTime updateTime;
         
             /**
              * 创建人
              */
             @ApiModelProperty("创建人")
             @TableField(fill = FieldFill.INSERT)
             private Long createUser;
         
             /**
              * 修改人
              */
             @ApiModelProperty("修改人")
             @TableField(fill = FieldFill.INSERT_UPDATE)
             private Long updateUser;
         
             /**
              * 是否删除
              */
             @ApiModelProperty("是否删除")
             @Delegate
             private Integer isDeleted;
         
         }
         

      2. package com.app.studypro.common;
         
         import io.swagger.annotations.ApiModel;
         import io.swagger.annotations.ApiModelProperty;
         import lombok.Data;
         
         import java.io.Serializable;
         import java.util.HashMap;
         import java.util.Map;
         
         @Data
         @ApiModel("返回接口")
         public class ResultBean<T> implements Serializable {
         
             private static final long serialVersionUID = -6759928086797729382L;
             /**
              * 编码：1成功，0和其它数字为失败
              */
             @ApiModelProperty("编码：1成功，0和其它数字为失败")
             private Integer code;
             /**
              * 错误信息
              */
             @ApiModelProperty("错误信息")
             private String msg;
             /**
              * 数据
              */
             @ApiModelProperty("数据")
             private T data;
             /**
              * 动态数据
              */
             @ApiModelProperty("动态数据")
             private Map map = new HashMap();
         
             public static <T> ResultBean<T> success(T object) {
                 ResultBean<T> r = new ResultBean<T>();
                 r.data = object;
                 r.code = 1;
                 return r;
             }
         
             public static <T> ResultBean<T> error(String msg) {
                 ResultBean r = new ResultBean();
                 r.msg = msg;
                 r.code = 0;
                 return r;
             }
         
             public ResultBean<T> add(String key, Object value) {
                 this.map.put(key, value);
                 return this;
             }
         
         }
         

   2. 描述controller类、方法及其方法参数：可以使用注解@Api、 @ApiOperation、@ApiImplicitParams、@ApiImplicitParam

      1. package com.app.studypro.controller;
         
         import com.app.studypro.common.ResultBean;
         import com.app.studypro.entity.User;
         import com.app.studypro.service.UserService;
         import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
         import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
         import io.swagger.annotations.Api;
         import io.swagger.annotations.ApiImplicitParam;
         import io.swagger.annotations.ApiImplicitParams;
         import io.swagger.annotations.ApiOperation;
         import lombok.extern.slf4j.Slf4j;
         import org.apache.commons.lang.StringUtils;
         import org.springframework.beans.factory.annotation.Autowired;
         import org.springframework.cache.annotation.CacheEvict;
         import org.springframework.cache.annotation.CachePut;
         import org.springframework.cache.annotation.Cacheable;
         import org.springframework.util.DigestUtils;
         import org.springframework.web.bind.annotation.*;
         
         import javax.servlet.http.HttpServletRequest;
         
         @RestController
         @RequestMapping("/users")
         @Slf4j
         @Api(tags = "用户管理接口")
         public class UserController {
         
             @Autowired
             private UserService userService;
         
             /**
              * 用户登录
              *
              * @param request
              * @param user
              * @return
              */
             @PostMapping("/login")
             @ApiOperation(value = "用户登录")
             public ResultBean<User> login(HttpServletRequest request, @RequestBody User user) {
         
         
                 return ResultBean.success(sqlUser);
             }
         
             /**
              * 用户退出
              *
              * @param request
              * @return
              */
             @PostMapping("/logout")
             @ApiOperation(value = "用户退出")
             public ResultBean<String> logout(HttpServletRequest request) {
                
                 return ResultBean.success("退出成功");
             }
         
             /**
              * 新增账号
              * 设置缓存名称为user-cache，将当前缓存名称的缓存全部失效
              *
              * @param user
              * @return
              */
             @CachePut(value = "userCache", key = "#result.data.id")
             @PostMapping
             @ApiOperation(value = "新增账号")
             public ResultBean<User> save(HttpServletRequest request, @RequestBody User user) {
                 
         
                 return ResultBean.success(user);
             }
         
             /**
              * 根据id修改用户信息
              *
              * @param user
              * @return
              */
             @ApiOperation(value = "根据id修改用户信息")
             @CacheEvict(value = "userCache", allEntries = true)
             @PutMapping
             public ResultBean<String> update(HttpServletRequest request, @RequestBody User user) {
                 
                 return ResultBean.success("用户信息修改成功");
             }
         
             /**
              * 根据id查询用户信息
              *
              * @param id
              * @return
              */
             @ApiOperation(value = "根据id查询用户信息")
             @Cacheable(value = "userCache3", key = "#id")
             @GetMapping("/{id}")
             public ResultBean<User> getById(@PathVariable Long id) {
                
                 return ResultBean.error("没有查询到对应用户信息");
             }
         
             /**
              * 用户信息分页
              *
              * @param page     当前页
              * @param pageSize 每页显示条数
              * @param username 用户名
              * @return 返回分页用户信息
              */
             @ApiOperation(value = "用户信息分页")
             @ApiImplicitParams({
                     @ApiImplicitParam(name = "page", value = "当前页", required = true),
                     @ApiImplicitParam(name = "pageSize", value = "每页显示条数", required = true),
                     @ApiImplicitParam(name = "username", value = "用户名", required = false)
             })
             @GetMapping("/page")
             @Cacheable(value = "userCache", key = "#page+'_'+#pageSize+'_'+#username", unless = "#result.data.total==0")
             public ResultBean<Page<User>> page(int page, int pageSize, String username) {
                 
                 return ResultBean.success(pageInfo);
             }
         
         }
         

4. 重启web服务之后，再访问接口文档的页面，我们可以发现接口文档中存在很多增加可读性的有效的接口信息。可以看出接口的中文描述，清晰的看到每一个接口是做什么的，接口方法参数什么含义，参数是否是必填的，响应结果的参数是什么含义等信息，都可以清楚的描述出来。这样来说，我们若是想要清晰的描述一个接口，就需要借助于Swagger给我们提供的注解

   1. ​​​​​​​