借老系统重构我准备写个OpenAPI3.1版的API管理工具(附录屏演示)

news/2024/11/7 15:18:07/

前段时间一直在忙公司老系统重构的方案设计,其中最大的重构点就是前后端分离。为了加快前后端协同开发和对接的工作效率,我决定写一个公司内部使用的OpenAPI3.1版的API管理工具。

文章目录

    • 有现成的工具为啥不用
    • 现有成熟方案
    • 初步成果展示
    • 录屏演示
    • 下一步计划

有现成的工具为啥不用

apiFox这样的API文档集成开发工具,功能强大又繁杂。作为企业使用,比较关注的几个重点:

  1. API的定义规范统一

    大家都遵循一套规范,最好是业界公认的。有了这样的API接口定义规范,自然市面上大部分厂商都会去实现这套规范开发出一些好用的插件和工具。从而面向市面公认规范的开发出来的工具才有普及性以及各种底层工具的支撑。因此选规范,远比选工具重要,这里我们采用业界公认的API设计规范 - Open API Specification(简称oas)

  2. 支持反向生成和部署代码

    这也应该是企业协同开发最关心的:一处维护,到处使用这就要求,基于一套定义,可以反向生成各种主流编码语言的代码,经过相关工具的编译、打包和发布流程,把API调用包和定义包部署起来。实现自己调用自己,左右互搏,那前端妹纸和后端码男就都成了吃瓜群众,再也没有那么多鸡毛蒜皮的羁绊了。都从对接方沦为了看客。

  3. 为软件开发、维护整个生命周期保驾护航,一体化流程

    既然沦为了“看客”,这一点功能是很有必要的。因为好的产品设计的简单,通吃各类人群,咱们的API工具不光开发、测试人员,前线的产品、运维人员都用的溜,由他们发起API变更,再经过审核,实现一键部署。这就要求产品具备人性化的API变更提醒和变更历史追溯,以确保开发人员及时投入“战斗”,仅关注于业务逻辑层的开发,加速软件整个生命周期的良好运转。

现有成熟方案

基于以上几点的考虑,还是决定自研一套企业内API接口文档协同工具,关注核心特性的实现以解放人力和生产力。前面说的业界统一的API定义规范是swagger官方搞出来的Open API Specification,简称oas。原先swagger是做框架层的工具的,提供项目依赖,实现代码注解,进而在运行时产出文档数据来形成文档。这种代码主导文档的方式,一度成为开发人员编码的负担。后来swagger官方反其道而行之,不再受限于工具,自己主导制定了oas规范。有了这套规范,别的厂商来实现相关工具,而它自己也开发出了oas生态的Swagger Hub,实现了天龙人的API一站式管理平台。而它的贡献也惠及平民众生,发布了让开发人员卸下沉重负担的Swagger Codegen代码生成器。据说这里有个小插曲,从该工具3.0发布开始,团队内部对产品开发方向产生分歧,引申出一条新的开发分支,也就是现在用的更多的OpenAPI Generator。另外,集成开发产品行业翘楚JetBrains也推出了基于oas定义所见即所得的Open API插件,让我们的API开发如虎添翼,直接起飞。

初步成果展示

要写一个能得到团队内部认可和被广泛使用的IT产品,绝非一朝一夕。先迈出这一步,就会发现路越走越宽。即便长时间还在山脚下仰望。现在初步完成的成果如下:

在这里插入图片描述

可以基于oas3的最新3.1.0规范扩展出一个定制版本的API生成器,能基于一份扩展的yaml格式的定义文件,来生成较为完美的DTO类和API接口;同时这份定义文件也能被ideaOpenAPI插件所应用以支持离线swagger文档查看和本地API调用和调试。在这个过程中,自己付出很多努力,对最新发布的Swagger Codegen生成器源码做了一个缺陷的修复和功能定制扩展的二次开发。涉及到这些包的源码二开:

在这里插入图片描述

录屏演示

Swagger生成器工具演示

下一步计划

现在的API定义还是写在一个文件中的,随着API接口模块的增多,这个文件将会变得非常臃肿。我们将通用的定义形式进行模型化处理,设计出一套数据库表结构来出存储,第一版先不引入版本的概念,后续慢慢一步步迭代。oas定义文件将按照选定的API模块使用freemarker模板来动态生成,以临时文件的形式,交给生成器执行生成目标代码。

后续将进一步使用element plusUI库来搭建简洁大气的webAPI维护界面,并通过gradle自定义插件的形式完成API制品包的生成和安装发布,以提供给项目通过依赖的形式集成进来。


http://www.ppmy.cn/news/1527465.html

相关文章

代理IP设置后IP不变?可能的原因及解决方法

在使用代理IP时,有时会遇到代理设置后IP地址却没有变化的情况。这种问题可能会让人感到困惑,但其实背后有多种原因。本文将详细探讨这些原因,并提供相应的解决方法,帮助你顺利解决问题。 可能的原因 代理IP设置后IP地址不变的原…

Netty 相关问题

传统网络编程存在的问题 传统网络编程存在以下问题: 线程创建开销:在Java中,创建线程需要调用操作系统API,这会消耗资源和时间。内存占用高:线程本身占用内存,创建过多线程会导致内存资源紧张。CPU使用率…

Uniapp + Vue3 + Vite +Uview + Pinia 分商家实现购物车功能(最新附源码保姆级)

Uniapp Vue3 Vite Uview Pinia 分商家实现购物车功能(最新附源码保姆级) 1、效果展示2、安装 Pinia 和 Uview3、配置 Pinia4、页面展示 1、效果展示 注意:这个演示图没有背景色,背景色建议在 App.vue 中新增代码实现全局背景色…

Qt_多元素控件

目录 1、认识多元素控件 2、QListWidget 2.1 使用QListWidget 3、QTableWidget 3.1 使用QListWidget 4、QTreeWidget 4.1 使用QTreeWidget 5、QGroupBox 5.1 使用QGroupBox 6、QTabWidget 6.1 使用QTabWidget 结语 前言: 在Qt中,控件之间…

4.qml单例模式

这里写目录标题 js文件单例模式qml文件单例模式 js文件单例模式 直接添加一个js文件到qml中 修改内容 TestA.qml import QtQuick 2.0 import QtQuick.Controls 2.12 import "./MyWork.js" as MWItem {Row{TextField {onEditingFinished: {MW.setA(text)}}Button…

第十八节:学习统一异常处理(自学Spring boot 3.x的第五天)

这节记录下如何通过AOP方式统一处理异常拦截。 第一步: 新建一个exception包,创建一个ExcetionHandler.java(名字随意取) package cn.wcyf.wcai.exception;import cn.wcyf.wcai.common.Result; import org.springframework.web…

mysql实用系列:日期格式化

在MySQL中,你可以使用DATE_FORMAT()函数来格式化日期。DATE_FORMAT() 函数通常用于格式化 DATETIME 或 TIMESTAMP类型的字段。这个函数允许你按照指定的格式来显示日期和时间。下面是一些常见的日期格式化的例子: 显示年-月-日: SELECT DATE_…

经典sql题(六)查找用户每月累积访问次数

使用聚合开窗查找用户每月累积访问次数,首先介绍一下使用 GROUP BY和开窗的区别 GROUP BY 行数变化:使用 GROUP BY 后,原始数据会按指定列进行分组,结果中每组只保留一行,因此行数通常减少。作用:适用于需…