一种应用于微服务工程接口文档检测的系统和方法与流程

本发明涉及计算机技术领域，具体而言，涉及一种应用于微服务工程接口文档检测的系统和方法。

背景技术：

随着互联网行业的迅速发展，程序员开发的代码量迅速增长，程序互相调用，接口量也大幅度增加。随之而来的问题就是接口在设计时往往需要编写大量的文档，而且编写完成之后还会经常改动，文档编写维护工作量大，文档与代码保持修改同步也是很大的工作量；接口文档不完善往往会增加对接双方的沟通成本。类似app的项目，前端会需要调用到后端接口，接口功能不实现会影响前端开发进度，就需要完善的接口文档去做mock数据，保证前端页面的开发进度。对于测试人员测新接口功能，接口文档更是重要参考的资料，接口测试人员了解接口最主要的依据就是接口文档。

为了提高开发效率以及测试效率，接口文档平台出现了。原先的接口文档管理一般都是开发人员自己维护word文档或者excel表格，然后给需要的人传阅。每个人写文档风格不一，就会在理解上出现偏差，还会出现开发人员离职导致接口文档丢失的情况。而现在通过接口平台，制定了接口录入规范，所有接口都可通过平台查询，有效提高了研发的效率。开发人员开发的接口功能、类型繁多，会有接口文档遗漏的情况。尤其是rpc接口，通常开发人员在开发过程中通过交流就可以调用到接口了，忽略了书写接口文档。

因此，亟待设计一种微服务接口的接口文档检测系统，以解决接口文档遗漏的问题，自动管理软件开发的接口信息。

技术实现要素：

本发明提供了一种应用于微服务工程接口文档检测的系统和方法，以至少解决相关技术中接口文档不能实现自动化管理，接口文档遗漏，软件整体研发效率低的问题。

根据本发明的一个方面，提供了一种应用于微服务工程接口文档检测的系统，包括：接口文档平台与ci/cd质量检测单元；其中，接口文档平台包括接口文档自动录入模块、页面展示模块；ci/cd质量检测单元包括提供者jar包更新检测模块、微服务接口遍历模块、文档检测分析模块：

所述接口文档自动录入模块，用于对新增、修改的接口进行接口文档自动录入；

所述提供者jar包更新检测模块，通过从maven私服获取最新微服务工程的jar包，同时新增或修改maven的pom文件，更新微服务工程的jar包；

所述微服务接口遍历模块，通过zookeeper获取微服务工程提供的服务，然后通过java反射机制对所述服务的接口进行遍历获取接口信息，所述接口信息包括但不限于工程名、接口名称、请求参数、描述信息；

所述接口文档检测分析模块，将微服务工程的接口信息与现有的接口文档进行对比分析，分析得出需要新增或者修改的接口文档的接口信息。

可选的，所述ci/cd质量检测单元还包括消息通知模块，利用websocket对开发人员发送需要新增或者修改的接口文档的通知信息，再同步将通知信息更新到接口文档平台的页面展示模块进行页面显示。

可选的，所述ci/cd质量检测单元还包括：接口用例补充模块，用于接收需要新增或者修改的接口文档的接口信息，并补充或者维护接口测试用例。

可选的，所述接口文档平台用于接口文档管理，同时支持自动化或者手动录入微服务接口文档、webapi类型接口文档、航旅私有协议接口文档。

可选的，所述接口文档平台的页面展示模块用于展示需要新增或者修改的接口文档的接口信息。

根据本发明的另一个方面，还提供了一种应用于微服务工程接口文档的检测方法，包括：

步骤1，通过读取工程代码注解的方式，对新增、修改的接口进行文档自动录入；

步骤2，每次工程代码上线前，获取maven私服上最新微服务工程jar包，同时修改maven的pom文件，更新微服务工程的jar包；

步骤3，获取最新微服务工程的工程代码接口，对工程代码接口进行遍历获取指定工程代码接口的接口信息，并存储到接口信息数据库；

步骤4，将接口信息数据库中的接口信息与现有的接口文档进行对比分析，得出需要新增或者修改的接口文档的接口信息；

步骤5，将需要新增或者修改的接口文档的接口信息通过websocket和接口平台页面转发；

步骤6，接收所述需要新增或者修改的接口文档的接口信息，并补充或者维护接口测试用例。

可选的，所述步骤1包括：

步骤1.1开发接口，根据接口规范写javadoc注释；

步骤1.2利用阿里rap开源的读注解的插件获取所述javadoc注释上的接口信息；

步骤1.3将所述接口信息录入接口文档平台，状态为待审核，需要负责人确认；

步骤1.4负责人审核通过，接口信息成功录入接口文档平台；审核不通过则放弃录入保留原有文档信息。

可选的，所述步骤2包括：

步骤2.1定时从maven私服上获取最新的微服务工程jar包信息，更新domain信息表；

步骤2.2工程代码上线前做ci/cd检测，根据微服务工程名获取最新微服务工程jar包；如果jar包没有升级则代表该微服务工程接口没有变动，直接跳出检测；如果jar包有升级则进行下一步；

步骤2.3根据该最新微服务工程jar包版本号，自动更新maven的pom文件，更新最新微服务工程的jar包；

步骤2.4重新打包检测工具，获取最新微服务工程代码的最新接口信息。

可选的，所述步骤3包括：

步骤3.1从zookeeper中取出当前微服务工程提供的服务的工程代码接口；

步骤3.2通过java反射机制获取当前微服务工程提供的服务的工程代码接口信息：工程名、接口名称、请求参数、描述信息；

步骤3.2将接口信息存储到redis缓存中。

可选的，所述步骤4包括：

步骤4.1从缓存中取出遍历出来的接口信息与现有接口文档对比分析，如果没有则需要新增接口文档，如果有改动则需要更新接口文档；

步骤4.2得到需要新增或者修改的接口文档，做为消息发送给amq。

可选的，所述步骤5包括：

步骤5.1从amq消息队列中取出需要补充或者修改的接口文档的接口信息：工程名、接口名称、请求参数、描述信息；

步骤5.2根据工程名获取负责人；

步骤5.3利用websocket协议向指定负责人发送补充接口文档的通知，展示在接口平台页面上；

步骤5.4将新接口、需要修改的接口通知给接口文档平台。

通过本发明，只需要开发人员在设计接口时按照规范写注解信息，就能够自动录入接口文档。同时结合ci/cd，在上线前对现有的接口文档和开发代码中的rpc接口进行分析检测，可以在工程上线前检测出需要补充文档的新接口、需要完善修改文档的接口。并通知开发人员补充文档，监督开发人员规范录入文档，测试人员针对这些变更信息及时补充维护接口测试用例，提高整体研发效率。

附图说明

此处所说明的附图用来提供对本发明的进一步理解，构成本申请的一部分，本发明的示意性实施例及其说明用于解释本发明，并不构成对本发明的不当限定。在附图中：

图1为本发明基于微服务接口的接口文档检测系统方框图；

图2为本发明基于微服务接口的接口文档检测系统的接口文档自动录入流程图；

图3为本发明基于微服务接口的接口文档检测系统的ci/cd接口文档检测流程图。

图4为本发明基于微服务接口的接口文档检测系统的消息通知模块流程图。

图5为本发明基于微服务接口的接口文档检测系统的消息通知模块通知给接口文档平台的新接口信息以及改动的接口信息。

具体实施方式

下文中将参考附图并结合实施例来详细说明本发明。需要说明的是，在不冲突的情况下，本申请中的实施例及实施例中的特征可以相互组合。

本发明实施例提供一种应用于微服务工程接口文档检测的系统，包括：接口文档平台与ci/cd质量检测单元；其中，接口文档平台包括接口文档自动录入模块、页面展示模块；ci/cd质量检测单元包括提供者jar包更新检测模块、微服务接口遍历模块、文档检测分析模块：

所述接口文档自动录入模块，用于对新增、修改的接口进行接口文档自动录入；

所述提供者jar包更新检测模块，通过从maven私服获取最新微服务工程的jar包，同时新增或修改maven的pom文件，更新微服务工程的jar包；

所述微服务接口遍历模块，通过zookeeper获取微服务工程提供的服务，然后通过java反射机制对所述服务的接口进行遍历获取接口信息，所述接口信息包括但不限于工程名、接口名称、请求参数、描述信息；

所述接口文档检测分析模块，将微服务工程的接口信息与现有的接口文档进行对比分析，分析得出需要新增或者修改的接口文档的接口信息。

本实施例中，所述ci/cd质量检测单元还包括消息通知模块，利用websocket对开发人员发送需要新增或者修改的接口文档的通知信息，再同步将通知信息更新到接口文档平台的页面展示模块进行页面显示。

本实施例中，所述ci/cd质量检测单元还包括：接口用例补充模块，用于接收需要新增或者修改的接口文档的接口信息，并补充或者维护接口测试用例。

本实施例中，所述接口文档平台用于接口文档管理，同时支持自动化或者手动录入微服务接口文档、webapi类型接口文档、航旅私有协议接口文档。

本实施例中，所述接口文档平台的页面展示模块用于展示需要新增或者修改的接口文档的接口信息。

根据本发明的另一个方面，还提供了一种应用于微服务工程接口文档的检测方法，包括：

步骤1，通过读取工程代码注解的方式，对新增、修改的接口进行文档自动录入；

步骤2，每次工程代码上线前，获取maven私服上最新微服务工程jar包，同时修改maven的pom文件，更新微服务工程的jar包；

步骤3，获取最新微服务工程的工程代码接口，对工程代码接口进行遍历获取指定工程代码接口的接口信息，并存储到接口信息数据库；

步骤4，将接口信息数据库中的接口信息与现有的接口文档进行对比分析，得出需要新增或者修改的接口文档的接口信息；

步骤5，将需要新增或者修改的接口文档的接口信息通过websocket和接口平台页面转发；

步骤6，接收所述需要新增或者修改的接口文档的接口信息，并补充或者维护接口测试用例。

本实施例中，所述步骤1包括：

步骤1.1开发接口，根据接口规范写javadoc注释；

步骤1.2利用阿里rap开源的读注解的插件获取所述javadoc注释上的接口信息；

步骤1.3将所述接口信息录入接口文档平台，状态为待审核，需要负责人确认；

步骤1.4负责人审核通过，接口信息成功录入接口文档平台；审核不通过则放弃录入保留原有文档信息。

本实施例中，所述步骤2包括：

步骤2.1定时从maven私服上获取最新的微服务工程jar包信息，更新domain信息表；

步骤2.2工程代码上线前做ci/cd检测，根据微服务工程名获取最新微服务工程jar包；如果jar包没有升级则代表该微服务工程接口没有变动，直接跳出检测；如果jar包有升级则进行下一步；

步骤2.3根据该最新微服务工程jar包版本号，自动更新maven的pom文件，更新最新微服务工程的jar包；

步骤2.4重新打包检测工具，获取最新微服务工程代码的最新接口信息。

本实施例中，所述步骤3包括：

步骤3.1从zookeeper中取出当前微服务工程提供的服务的工程代码接口；

步骤3.2通过java反射机制获取当前微服务工程提供的服务的工程代码接口信息：工程名、接口名称、请求参数、描述信息；

步骤3.2将接口信息存储到redis缓存中。

本实施例中，所述步骤4包括：

步骤4.1从缓存中取出遍历出来的接口信息与现有接口文档对比分析，如果没有则需要新增接口文档，如果有改动则需要更新接口文档；

步骤4.2得到需要新增或者修改的接口文档，做为消息发送给amq。

本实施例中，所述步骤5包括：

步骤5.1从amq消息队列中取出需要补充或者修改的接口文档的接口信息：工程名、接口名称、请求参数、描述信息；

步骤5.2根据工程名获取负责人；

步骤5.3利用websocket协议向指定负责人发送补充接口文档的通知，展示在接口平台页面上；

步骤5.4将新接口、需要修改的接口通知给接口文档平台。

本发明中使用到的部分术语：

阿里rap：是一个gui的web接口管理工具。

ci/cd：是持续集成(continuousintegration)和持续部署(continuousdeployment)简称。指在开发过程中自动执行一系列脚本来减低开发引入bug的概率，在新代码从开发到部署的过程中，尽量减少人工的介入。

maven私服：私服是一种特殊的远程仓库，它是架设在局域网内的仓库服务，私服代理广域网上的远程仓库，供局域网内的用户使用。当多人项目开发的时候，尤其聚合项目开发，项目和项目之间需要有依赖关系，通过maven私服，可以保存互相依赖的jar包，这样的话就可把多个项目整合到一起。

如图1所示，本发明的基于微服务接口的接口文档检测系统由接口文档平台和ci/cd检测系统构成，接口文档平台具有存储、管理、展示接口文档的功能；

ci/cd检测系统包括提供者jar包更新模块、微服务接口遍历模块、接口文档分析模块、消息通知模块、接口用例补充模块。ci/cd检测系统由jenkins衔接，负责对提交ci/cd检测的工程进行质量评估，包括代码扫描、单元测试、包名规范检测以及本发明的微服务接口文档检测。其微服务接口的接口文档检测包括如下步骤：

步骤1，程序员开发微服务接口，接口文档录入模块通过读取代码注解的方式，自动化补充、修改接口文档；开发人员在设计开发接口代码时，可以通过手动录入的形式及将该接口文档录入到接口平台，或者可以通过配置javadoc注释，提交代码到git仓库。然后打包编译，同时更新私服中的jar包版本。

步骤2，每次工程代码上线前，jar包检测模块获取私服上最新的工程jar包，同时修改检测工程的pom文件，更新检测系统依赖的服务提供者的jar包，保证获取后台代码的最新接口信息。

步骤3，微服务接口遍历模块获取接口信息，根据最新的微服务提供者获取指定工程代码接口的接口名、请求参数信息，并存储到接口信息数据库。

步骤4，文档检测分析模块将接口信息和接口文档进行分析对比，得出需要新增或者修改的接口信息；如果程序员没有写新接口文档则不能通过ci/cd质量检测。

步骤5，消息通知模块将现有接口文档问题通过websocket协议和接口平台页面实时通信转发通知给各项目负责人；同时通知自动化测试平台需要新补充接口用例的接口以及需要维护更改接口用例的接口。

步骤6，接口用例补充模块用于接收补充用例消息，测试人员根据消息补充自动化接口测试用例。

如图2所示，本发明的基于微服务接口的接口文档系统，其接口文档自动录入模块的流程图，包括如下步骤：

步骤1.1程序员开发接口根据接口规范写javadoc注释；

步骤1.2利用阿里rap开源的插件读接口注解获取接口信息；

步骤1.3接口信息录入接口文档平台，状态为待审核，需要负责人确认；

步骤1.4负责人审核通过，接口信息成功录入接口文档平台；审核不通过则放弃录入保留原有文档信息。

如图3所示，本发明基于微服务接口的接口文档系统，其ci/cd接口文档检测流程图，包括了提供者jar包更新模块、微服务接口遍历模块、接口文档分析模块，其步骤如下：

步骤2.1定时从maven私服上获取提供者工程jar包信息，更新domain信息表；

步骤2.2工程上线前做ci/cd检测，根据工程名获取最新工程jar包。如果jar包没有升级则代表该工程微服务接口没有变动，直接跳出检测；如果jar包有升级则进行下一步；

步骤2.3根据将该工程最新jar包版本号，自动更新接口文档检测工程的pom文件，依赖最新版本jar包；

步骤2.4重新打包检测工具，用于获取最新微服务接口信息。

步骤3.1从zookeeper中取出当前提供者提供的服务；

步骤3.2通过java反射机制获取所有接口信息：接口名称、请求参数、描述信息；

步骤3.3将接口信息存储到redis缓存中。

步骤4.1从缓存中取出遍历出来接口信息的对比现有接口文档分析，如果没有则需要新增接口文档，如果有改动则需要更新接口文档；

步骤4.2得到需要新增或者修改的接口文档，做为消息发送给amq消息队列。

如图4所示，本法发明基于微服务接口的接口文档系统，其消息通知模块负责将检测结果分别通知给开发和测试人员，其中步骤包括：

步骤5.1从amq消息队列中取出需要补充或者修改的接口文档信息：工程、接口名称、请求参数、描述信息；

步骤5.2接口平台管理根据工程名获取负责人；

步骤5.3利用websocket协议向指定负责人发送补充接口文档的通知，展示在接口平台页面上；

步骤5.4将新接口、需要修改的接口通知给自动化接口测试平台。

图5为本发明消息通知模块通知给接口文档平台的新接口信息以及改动的接口信息。

通过本发明，只需要开发人员在设计接口时按照规范写注解信息，就能够自动录入接口文档。同时结合ci/cd，在上线前对现有的接口文档和开发代码中的rpc接口进行分析检测，可以在工程上线前检测出需要补充文档的新接口、需要完善修改文档的接口。并通知开发人员补充文档，监督开发人员规范录入文档，测试人员针对这些变更信息及时补充维护接口测试用例，提高整体研发效率。

以上所述仅为本发明的优选实施例而已，并不用于限制本发明，对于本领域的技术人员来说，本发明可以有各种更改和变化。凡在本发明的精神和原则之内，所作的任何修改、等同替换、改进等，均应包含在本发明的保护范围之内。