基于若依框架实践（三）：通过swagger定义接口

疯癫的老码农

已于 2023-09-19 11:10:13 修改

阅读量3.1k

点赞数 6

分类专栏： springboot swagger java 文章标签： springboot 接口隔离原则 java spring maven spring cloud

于 2023-09-19 11:08:31 首次发布

本文链接：https://blog.csdn.net/HWTwilight/article/details/133015107

版权

java 同时被 3 个专栏收录

13 篇文章 0 订阅

订阅专栏

springboot

6 篇文章 0 订阅

订阅专栏

swagger

2 篇文章 0 订阅

订阅专栏

相关文章：

基于若依框架实践（一）：总体的介绍_疯癫的老码农的博客-CSDN博客

基于若依框架实践（二）：通过profile隔离不同环境配置_疯癫的老码农的博客-CSDN博客

写作背景

做了很多年的软件研发，写的文章不多、总结的也不多，曾经做过的积累或者后续的遇到的技术难点还是考虑稍微写一写，算是给自己的一个记录吧~。

近期基于若依框架开发了好几个小系统, 系统从功能上既包含管理台功能也有自己的前台部分，借此机会做一个总结，并且分享给有需要的同学,不喜勿喷，有劳各位看官费神了。

本文简介

在 SpringBoot 中，我们可以通过 swagger框架来定义接口。当前软件应用开发中，很多情况下采用了前后端分离开发的模式，为提升协同效率必然提前把接口协议先定义好，然后分头去开发。本文是基于若依框架中实践了swagger的使用，以及总结了应用过程中遇到的问题和如何解决这些问题的。

框架优势

在 SpringBoot 项目中使用 Swagger，具有以下优势和价值：

提高团队开发效率：Swagger 是一个 API 文档在线自动生成工具，可以为团队成员提供清晰的 API 文档，方便团队成员了解 API 的使用方法，从而提高团队的开发效率。

降低沟通成本：清晰的 API 文档可以帮助团队成员更好地理解 API 的功能和使用方法，降低团队成员之间的沟通成本。

自动生成文档：Swagger 可以自动生成 API 文档，省去了手动编写文档的过程，减轻了开发人员的负担。

实时更新文档：Swagger 可以实时更新文档，当 API 发生变化时，可以立即在文档中看到变化，保证了文档的准确性。

方便测试：Swagger 可以生成 API 测试报告，方便开发人员进行 API 测试，提高测试效率。

实践总结

下面通过具体场景来表达清晰，我如何进行swagger实践的，请耐心阅读~

1、增加工程依赖

增加如下两个工程

ruoyi-business：里面包含业务功能实现，包括对swagger框架的依赖

ruoyi-swagger：定义测试swagger的接口样例

如下图所示：

ruoyi-business中增加了swagger所需的依赖，如下依赖：

        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.6.2</version>
        </dependency>

        <!-- lombok -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
        </dependency>

ruoyi-swagger中增加了ruoyi-business的依赖，如下依赖：

        <!-- business-->
        <dependency>
            <groupId>com.ruoyi</groupId>
            <artifactId>ruoyi-business</artifactId>
        </dependency>

2、进行框架调整

为了尽量减少框架的改动，采取如下的改动方式：

调整TableDataInfo

调整TableDataInfo为TableDataInfo<T>，这个是改动了若依的框架代码，但是改动不大，

详情如下：

/**
 * 表格分页数据对象
 * 
 * @author ruoyi
 */
@Data
@ApiModel(value = "表格分页数据对象")
public class TableDataInfo<T> implements Serializable
{
    private static final long serialVersionUID = 1L;

    /** 总记录数 */
    private long total;

    /** 列表数据 */
    private List<T> rows;

    /** 消息状态码 */
    private int code;

    /** 消息内容 */
    private String msg;

    /**
     * 表格数据对象
     */
    public TableDataInfo()
    {
    }

    /**
     * 分页
     * 
     * @param list 列表数据
     * @param total 总记录数
     */
    public TableDataInfo(List<T> list, int total)
    {
        this.rows = list;
        this.total = total;
    }
}

增加AjaxResResult


/**
 * 操作消息提醒
 * 
 * @author twilight
 */
@Data
@ApiModel(value = "通用响应对象")
public class AjaxResResult<T>
{
    /** 状态码 */
    private int code;

    /** 返回内容 */
    private String msg;

    /** 数据对象 */
    private T data;

    /**
     * 初始化一个新创建的 AjaxResult 对象，使其表示一个空消息。
     */
    public AjaxResResult()
    {
    }

    /**
     * 初始化一个新创建的 AjaxResult 对象
     *
     * @param code 状态码
     * @param msg 返回内容
     */
    public AjaxResResult(int code, String msg)
    {
        this.code = code;
        this.msg = msg;
    }

    /**
     * 初始化一个新创建的 AjaxResult 对象
     *
     * @param code 状态码
     * @param msg 返回内容
     * @param data 数据对象
     */
    public AjaxResResult(int code, String msg, T data)
    {
        this.code = code;
        this.msg = msg;
        if (StringUtils.isNotNull(data))
        {
            this.data = data;
        }
    }

    /**
     * 返回成功消息
     * 
     * @return 成功消息
     */
    public static AjaxResResult success()
    {
        return AjaxResResult.success("操作成功");
    }

    /**
     * 返回成功数据
     * 
     * @return 成功消息
     */
    public static AjaxResResult success(Object data)
    {
        return AjaxResResult.success("操作成功", data);
    }

    /**
     * 返回成功消息
     * 
     * @param msg 返回内容
     * @return 成功消息
     */
    public static AjaxResResult success(String msg)
    {
        return AjaxResResult.success(msg, null);
    }

    /**
     * 返回成功消息
     * 
     * @param msg 返回内容
     * @param data 数据对象
     * @return 成功消息
     */
    public static AjaxResResult success(String msg, Object data)
    {
        return new AjaxResResult(HttpStatus.SUCCESS, msg, data);
    }

    /**
     * 返回错误消息
     * 
     * @return
     */
    public static AjaxResResult error()
    {
        return AjaxResResult.error("操作失败");
    }

    /**
     * 返回错误消息
     * 
     * @param msg 返回内容
     * @return 警告消息
     */
    public static AjaxResResult error(String msg)
    {
        return AjaxResResult.error(msg, null);
    }

    /**
     * 返回错误消息
     * 
     * @param msg 返回内容
     * @param data 数据对象
     * @return 警告消息
     */
    public static AjaxResResult error(String msg, Object data)
    {
        return new AjaxResResult(HttpStatus.ERROR, msg, data);
    }

    /**
     * 返回错误消息
     * 
     * @param code 状态码
     * @param msg 返回内容
     * @return 警告消息
     */
    public static AjaxResResult error(int code, String msg)
    {
        return new AjaxResResult(code, msg, null);
    }
}

增加BsBaseController

/**
 * @author twilight
 * @since V1.0
 */
@Slf4j
public class BsBaseController extends BaseController {

    /**
     * 返回成功消息
     */
    public AjaxResResult successRes(Object data)
    {
        return AjaxResResult.success(data);
    }

    /**
     * 响应返回结果
     *
     * @param rows 影响行数
     * @return 操作结果
     */
    protected AjaxResResult toAjaxRes(int rows)
    {
        return rows > 0 ? AjaxResResult.success() : AjaxResResult.error();
    }
}

3、编写模型对象

/**
 * @author twilight
 * @since V1.0
 */
@Data
@ApiModel(value = "SwaggerModelVo对象")
public class SwaggerModelVo {

    /** 搜索值 */
    private String searchValue;

    /** 创建者 */
    private String createBy;

    /** 创建时间 */
    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private Date createTime;

    /** 更新者 */
    private String updateBy;
}

4、编写接口定义

/**
 * @author twilight
 * @since V1.0
 */
@Api(tags = "swagger测试接口")
@RestController
@RequestMapping("/swagger")
public class SwaggerAction extends BsBaseController
{
    /**
     * response数据结构准确1
     */
    @ApiOperation(value = "response数据结构准确1")
    @GetMapping("/test001")
    public TableDataInfo<SwaggerModelVo> test001(@RequestBody SwaggerModelVo smvo)
    {
        List<SwaggerModelVo> list = new ArrayList<>();
        return getDataTable(list);
    }

    /**
     * response数据结构不准确2
     */
    @ApiOperation(value = "response数据结构不准确2")
    @GetMapping("/test002")
    public AjaxResult test002(@RequestBody SwaggerModelVo smvo)
    {
        List<SwaggerModelVo> list = new ArrayList<>();
        return success(list);
    }

    /**
     * response数据结构准确3
     */
    @ApiOperation(value = "response数据结构准确3")
    @GetMapping("/test003")
    public AjaxResResult<SwaggerModelVo> test003(@RequestBody SwaggerModelVo smvo)
    {
        List<SwaggerModelVo> list = new ArrayList<>();
        return successRes(list);
    }
}

5、查看接口定义

/dev-api/swagger/test001这个接口是可以看出来具体的接口入参和出参接口定义的

入参数据类型：

出参数据类型：

/dev-api/swagger/test002这个接口是可以看出来具体的接口出参就不太准确

入参数据类型：与/dev-api/swagger/test001一致

出参数据类型：

/dev-api/swagger/test003这个接口是可以看出来具体的接口入参和出参接口定义的

入参数据类型：与/dev-api/swagger/test001一致

出参数据类型：

6、实践经验总结

接口中的入参和出参不要使用如Map之类的数据结构，这样swagger出来的接口定义数据接口不是很明确。

查看接口的定义地址：http://localhost:8080/swagger-ui/index.html#

项目源码

RuoYi-Vue-Enhance: 本项目初始化源码来源于ruoyi-vue V3.8.6版本，在此基础上增加了一些内容，用于自己学习、记录和总结，并且分享给大家https://gitee.com/ricky_kai/ruoyi-vue-enhance.git

疯癫的老码农

关注

6
点赞
踩
16

收藏

觉得还不错? 一键收藏
打赏
0
评论
基于若依框架实践（三）：通过swagger定义接口

在 SpringBoot 中，我们可以通过 swagger框架来定义接口。当前软件应用开发中，很多情况下采用了前后端分离开发的模式，为提升协同效率必然提前把接口协议先定义好，然后分头去开发。本文是基于若依框架中实践了swagger的使用，以及总结了应用过程中遇到的问题和如何解决这些问题的。
复制链接

扫一扫