【Spring Boot】Swagger的常用注解

news2024/11/26 23:29:36

在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("是否删除")
    @Delegate
    private 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 {

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

}

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