当前位置： 首页 > article >正文

【Spring Boot】Swagger的常用注解

article 2024/11/20 6:58:05
  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. ​​​​​​​


http://www.kler.cn/a/146705.html

相关文章：

  • 《网络风险及网络安全》培训总结
  • 高阶云服务-ELB+AS
  • CSS遮罩：mask
  • HCIP --OSI七层参考模型回顾、TCP/UDP协议复习
  • vue 常用特性 ( 计算属性 | 侦听器 | 过滤器 )
  • Ascend C算子性能优化实用技巧05——API使用优化
  • 评测｜PolarDB MySQL 版 Serverless
  • 【Axure高保真原型】3D金字塔图_移入显示数据标签
  • C++ 文件和流、异常处理、动态内存、预处理器
  • 嵌入式设备视频编码比较：H.264、H.265、MPEG-2和MJPG
  • Feign接口请求返回异常 no suitable HttpMessageConvert found for response type
  • 卷积神经网络（CNN）车牌识别
  • csgo/steam搬砖项目新手教程
  • 6.12找树左下角的值（LC513-M）
  • TCP知识点
  • PT里如何针对某个模块设置false path
  • 【初始前后端交互+原生Ajax+Fetch+axios+同源策略+解决跨域】
  • OpenAI神秘项目Q-star曝光，人类永生或灭绝，将在我们有生之年发生
  • Python---练习：使用Python函数编写通讯录系统
  • Mindomo Desktop for Mac免费思维导图软件，助您高效整理思维
  • Linux系统---僵尸进程、孤儿进程
  • Linux网络——数据链路层
  • Node.js入门指南（四）
  • Open Feign 源码解析(一) --- FactoryBean的妙用
  • 《尚品甄选》：后台系统——结合redis实现用户登录
  • sqli-labs（4）