统一API设计管理平台简介及改造记录

Posted 2021-05-01 TCTP

背景介绍

在当前开发过程管理调研活动中，跨部门/跨系统协同经常遇到挑战，主要反映在接口管理方面。一是沟通成本高，全行无统一的发布接口文档方式；二是跨部门联调，接口变更无法及时周知全面，出现交易异常时，查问题耗时加多。联调耗时耗力，上下游系统不通。

于是，建立统一的API管理平台及管理机制，建立相应的标准，并且依托API管理平台进行扩展，将各系统环境的接口的稳定性可视化、智能化管理成了目前亟待解决的问题。

 产品选型 ·

在调研了目前各种主流接口文档协作平台后，在devdocs/slatedocs/Sphinx/CRAP-Api/eolinker/RAP2/YApi/confuluence/apizza等中考虑收费、开源和社区成熟度等因素后选择YApi来进行二次开发。立项后项目命名为APIDesign。

 APIDesign简介 ·

APIDesign核心功能为接口文档管理，附带Mock测试，接口测试，场景测试，环境管理，Wiki等等一系列功能。

APIDesign的接口文档管理相对于ShowDoc来说为约束性结构化数据，固定选项的约束性减少了接口定义的模糊性与歧义，如下图一个简单接口：

接口功能页的测试集合Tab分页提供了可生成测试报告的测试集，用户可以从接口列表导入接口，选择对应保存的环境来生成对应的针对接口层面的测试以及自定义的场景测试。如下图所示：

此项功能的意义在于业务的小幅迭代情况下，测试可以快速的给出回归报告，接口测试和特定的场景测试可以达到秒级的出报告，大幅的节省了时间。

APIdesign本身的数据管理功能也可以支持多种格式的数据的导入导出(swagger/json/postman/markdown/html等)，方便做各种接口数据的分享。如下图所示：

此外，APIDesign支持开放API接口，使用项目的token可以调用对应开放API来实现文档的各种操作，方便进一步高阶的应用。

APIDesign的定制化改造 ·

• RMB展示

• 接口文档快速生成

在以上问题背景下，我们引入了插件+注解的解决方案：我们提供了一套完善的注解，代码中只要参数使用了注解，在Idea开发工具中一键点击生成，即可生成。由于注解具有强格式性约束，一套简单明了的注解，对于开发来说是没有学习成本且可以节省大量时间。根据目前使用的用户反馈，此种方法对于文档的维护效率大大增加。

此外我们也有一套完善的参数验证逻辑可以进一步集成到代码中进一步帮助用户验证参数的正确性，省去参数验证烦恼。

可以看到，在此种操作下，新创建/修改文档的操作将会变得极其轻松，开发维护单个接口文档的耗时将会从之前手写一个高质量接口的平均15-20分钟上下缩短到几分钟。

• 代码的快速生成

• ShowDoc用户无感知迁徙

为此，我们首先用插件的模式在Tab分页中接口同级别Tab后添加了“文档”功能，实现了同等功能Markdown界面。其次，做了分步引流的操作：showDoc登录提示用户，服务即将关停，提供迁徙服务。同时，我们制作了对应的迁徙功能，用户只要输入showDoc用户名和密码，即可查询展示名下项目，点击同步按钮即可一键同步至APIDesign平台的“文档”Tab分页下，真正的实现了用户的一键迁徙。

可以看出用户基本是零成本的切换至新平台的。在长期使用趋势中，我们仍然会考虑“如何引导用户使用结构化接口文档功能”，从而让文档Tab中的非结构化接口逐步移除，使得文档Tab分页真正承担文档的功能。从而对未来的和其他系统例如DPMS，ITSM等系统集成时能够更好的完成整个开发生命周期的协同管理（涉及接口方向）。

APIDesign的迭代方向 ·

在目前满足基本使用的情况下，除了持续修改使用缺陷，我们根据现有的业务需求将会在平台未来有计划的添加以下支持

• 更好的测试支持

另外更好的和DPMS集成有关测试模块也是一个选择，我们的场景中可以完成测试的基本流程，可以把结果反馈到DPMS的开发-测试流程中，用来完善DPMS的测试报告结果管理。

• 完善开发流程生命周期管理

• 更易使用的交互

作者简介

frankzhou(周瑞哲)

基础科技产品部/后台开发室