【Spring Boot】Swagger的常用注解

在Swagger的开发过程中，我们需要在Controller代码等处添加相应的注解，以便可以提高生成的接口文档的可读性

为了解决这些问题，Swagger提供了很多的注解，通过这些注解，我们可以更好更清晰的描述我们的接口，包含接口的请求参数、响应数据、数据模型等信息。其核心的注解主要包含以下信息：

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

示例用法

描述实体类：使用注解@ApiModel、@ApiModelProperty来描述实体类及其类的属性

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("是否删除")@Delegateprivate Integer isDeleted;}

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;}}

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

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 {@Autowiredprivate 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)@PutMappingpublic 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);}}

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