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

前段时间一直在忙公司老系统重构的方案设计，其中最大的重构点就是前后端分离。为了加快前后端协同开发和对接的工作效率，我决定写一个公司内部使用的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接口；同时这份定义文件也能被idea的OpenAPI插件所应用以支持离线swagger文档查看和本地API调用和调试。在这个过程中，自己付出很多努力，对最新发布的Swagger Codegen生成器源码做了一个缺陷的修复和功能定制扩展的二次开发。涉及到这些包的源码二开：

录屏演示

下一步计划

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

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