基于若依框架实践(三):通过swagger定义接口 |
您所在的位置:网站首页 › 若依如何使用 › 基于若依框架实践(三):通过swagger定义接口 |
相关文章: 基于若依框架实践(一):总体的介绍_疯癫的老码农的博客-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-swagger中增加了ruoyi-business的依赖,如下依赖: com.ruoyi ruoyi-business 2、进行框架调整为了尽量减少框架的改动,采取如下的改动方式: 调整TableDataInfo调整TableDataInfo为TableDataInfo,这个是改动了若依的框架代码,但是改动不大, 详情如下: /** * 表格分页数据对象 * * @author ruoyi */ @Data @ApiModel(value = "表格分页数据对象") public class TableDataInfo implements Serializable { private static final long serialVersionUID = 1L; /** 总记录数 */ private long total; /** 列表数据 */ private List rows; /** 消息状态码 */ private int code; /** 消息内容 */ private String msg; /** * 表格数据对象 */ public TableDataInfo() { } /** * 分页 * * @param list 列表数据 * @param total 总记录数 */ public TableDataInfo(List list, int total) { this.rows = list; this.total = total; } } 增加AjaxResResult /** * 操作消息提醒 * * @author twilight */ @Data @ApiModel(value = "通用响应对象") public class AjaxResResult { /** 状态码 */ 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 test001(@RequestBody SwaggerModelVo smvo) { List list = new ArrayList(); return getDataTable(list); } /** * response数据结构不准确2 */ @ApiOperation(value = "response数据结构不准确2") @GetMapping("/test002") public AjaxResult test002(@RequestBody SwaggerModelVo smvo) { List list = new ArrayList(); return success(list); } /** * response数据结构准确3 */ @ApiOperation(value = "response数据结构准确3") @GetMapping("/test003") public AjaxResResult test003(@RequestBody SwaggerModelVo smvo) { List list = new ArrayList(); return successRes(list); } } 5、查看接口定义/dev-api/swagger/test001这个接口是可以看出来具体的接口入参和出参接口定义的 入参数据类型: 出参数据类型: 入参数据类型:与/dev-api/swagger/test001一致 出参数据类型: 入参数据类型:与/dev-api/swagger/test001一致 出参数据类型: 接口中的入参和出参不要使用如Map之类的数据结构,这样swagger出来的接口定义数据接口不是很明确。 查看接口的定义地址:http://localhost:8080/swagger-ui/index.html# 项目源码RuoYi-Vue-Enhance: 本项目初始化源码来源于ruoyi-vue V3.8.6版本,在此基础上增加了一些内容,用于自己学习、记录和总结,并且分享给大家 |
今日新闻 |
点击排行 |
|
推荐新闻 |
图片新闻 |
|
专题文章 |
CopyRight 2018-2019 实验室设备网 版权所有 win10的实时保护怎么永久关闭 |