CN113094093A - 一种基于互联网金融系统从源码生成系统交互的api文档的方法 - Google Patents

Abstract

本发明属于信息技术领域，公开了一种基于互联网金融系统从源码生成系统交互的API文档的方法，包括以下几个环节，S1:api管理系统中进行配置环节；S2:开发人员提交代码环节；S3:devops触发事件环节；S4:api管理系统工作环节；S5:静态页面展示环节。本发明对已有项目的入侵性很小，又能解决新项目的快速接入，能够快速地推广到各个系统，使各个系统都快速地使用起来；同时开发人员也只需要付出较小的对接成本，只需要在对接前提供相应的代码库进行相关的配置即可；而且生成的API文档进行全行的集中管理，同一个口径输出API文档，并且始终保持和源码一致，自动伴随源码的更新而更新。

Description

一种基于互联网金融系统从源码生成系统交互的API文档的 方法

技术领域

本发明属于信息技术领域，具体涉及一种基于互联网金融系统从源码生成系统交互的API文档的方法。

背景技术

随着互联网银行的业务日益增多，业务创新也日益增多，一个产品的开发可能涉及到几十甚至上百个系统，系统直接的交互都是通过各个系统的API文档进行交互。传统方案是系统间交互采用excel或者world的方式进行系统间的交互，每当系统有API需要更新的时候，即将相应的API文档更新给系统的上下游系统。

由于互联网业务的日益扩展，系统功能的迭代越来越频繁，系统交互的频率也越来越高，对系统交互的API文档的准确性也越来越高了，采用excel或者world的方式进行系统间的交互的传统方案已经越来越不适应现在的需求。其原因在于，采用传统方案，各个系统在接收到新需求的第一件事情就是编写系统交互的API文档。然后各个系统通过上下游提供的API文档展开相应的代码开发，如果一旦涉及到某个系统的API文档需要更新迭代的时候，会通过开发人员到项目经理到上下游系统，这样当某个系统迭代的频率很高的时候，会导致所有上下游系统拿到的API文档不是最新的API文档，从而导致开发出来的应用也并非满足实际需求，会严重影响项目的进度和项目交付的质量。

近些年，行业内又提出过另一方案。采用注解的方式进行文档的处理，即可完成相应的代码处理。开发人员在进行代码提交的时候编写自定义的一套注解进行编写，对于历史的项目也可以进行相应的改造。例如：采用swagger标签的方式进行实施，swagger是一款RESTFUL接口的文档在线自动生成功能软件，能满足绝大多数常见，对源码的入侵性非常强。该方案对对项目的入侵性很小，风险可控，代价较小。但是采用注释的方式进行文档的处理，对于新的项目可能比较适合，但是对于已有项目的改造，改造成本和风险相对较高。

综上，对于我行来说，银行系统采用目前系统交互的方法的主要缺点如下：

1、系统交互的文档很有可能不是最新的；

2、各个系统拿到的系统交互的文档的版本很有可能不一致；

3、文档中的API字段可能跟代码中不一致；

4、全行系统不能进行集中化管理，各个系统的文档分布到各个系统的开发人员的手中；

5、对于新的项目可能比较适合，但是对于已有项目的改造，改造成本和风险相对较高。

因此我们迫切需要一种处理方案，即要对已有项目的入侵性很小，又能解决新项目的快速接入，这样才能将该方法快速地推广到全行的各个系统，使各个系统都快速地使用起来。同时开发人员也只需要付出较小的对接成本，只需要在对接前提供相应的代码库进行相关的配置即可。生成的API文档进行全行的集中管理，同一个口径输出API文档，并且始终保持和源码一致，自动伴随源码的更新而更新。

发明内容

基于以上问题，本发明提供一种基于互联网金融系统从源码生成系统交互的API文档的方法，该方法对已有项目的入侵性很小，又能解决新项目的快速接入，能够快速地推广到各个系统，使各个系统都快速地使用起来；同时开发人员也只需要付出较小的对接成本，只需要在对接前提供相应的代码库进行相关的配置即可；而且生成的API文档进行全行的集中管理，同一个口径输出API文档，并且始终保持和源码一致，自动伴随源码的更新而更新。

为解决技术问题，本发明所采用的技术方案是：

为了便于理解方案，首先我们对方案内的一些名词进行解释。

API(Application Programming Interface，应用程序接口)是一些预先定义的接口(如函数、HTTP接口)，或指软件系统不同组成部分衔接的约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机制的细节。

系统：系统一词来源于英文system的音译，即若干部分相互联系、相互作用，形成的具有某些功能的整体。这里特指银行为各个业务服务的系统或者应用。

DevOps(Development和Operations的组合词)是一组过程、方法与系统的统称，用于促进开发(应用程序/软件工程)、技术运营和质量保障(QA)部门之间的沟通、协作与整合。它是一种重视“软件开发人员(Dev)”和“IT运维技术人员(Ops)”之间沟通合作的文化、运动或惯例。透过自动化“软件交付”和“架构变更”的流程，来使得构建、测试、发布软件能够更加地快捷、频繁和可靠。它的出现是由于软件行业日益清晰地认识到：为了按时交付软件产品和服务，开发和运维工作必须紧密合作。

code+2：代码在入库的时候，需要代码仓库的拥有者或者具有审核资格的人进行代码审核，只有在代码审核通过的时候，才做code+2的操作，只有code+2的时候，代码才能入库。

本发明的技术方案内容如下。

一种基于互联网金融系统从源码生成系统交互的API文档的方法，包括以下几个环节，

S1:api管理系统中进行配置环节，代码开发人员或者系统负责人在api管理系统中进行配置，对系统/应用的相关信息进行配置，为自动生成API文档提供前置条件；

S2:开发人员提交代码环节，开发人员接收需求开发代码，同时编写相应的注释，然后直接提交代码到git仓库；

S3:devops触发事件环节，代码在进行code+2的时候，devpos会自动触发相应的事件，自动调用api管理中心的API，触发生成自动生成API文档的功能；

S4:api管理系统工作环节，当devops调用的API的时候，自动取拉取该系统的代码，进行相应的解析，保存到数据库中；

S5:静态页面展示环节，需要查看相应的API文档时，登录api管理系统进行查看。

在本发明一实施例中，在S1环节中包括以下步骤，

步骤S11：代码开发人员或者系统负责人提交需要api管理系统的配置给api管理系统的系统管理员进行配置；

步骤S12：api管理系统的系统管理员对系统/应用的相关信息进行配置，包括系统/应用的名称、代码仓库、负责人，配置的目的是为了后续自动生成API文档提供前置条件。

在本发明一实施例中，在S3环节中包括以下步骤，

步骤S31：Devops在检测到代码进行code+2的时候自动触发相应的事件，同时自己主动抓取当前系统/应用的分支信息，把当前系统/应用的所有分支信息写入到一个文件，等待api管理系统来进行拉取，为后续API版本与分支保持一致提供数据。

在本发明一实施例中，在S3环节中包括以下步骤，

步骤S32：Devops在检测到代码进行code+2的时候自动触发相应的事件，调用api管理系统的相应的API，触发生成自动生成API文档的功能。

在本发明一实施例中，在S4环节中包括以下步骤，

步骤S41:接收到devops调用的API的时候，自动取拉取该系统的代码；

步骤S42：拉取到相应的代码的时候，检测该项目文件的完整性；

步骤S43：当检测到应用的文件完整的时候，则开始解析该项目下的所有文件，只要满足文件自定义的相应注释的即进行相应的解析；

步骤S44：解析当前代码的分支，更新API的版本，始终将API的版本与分支信息保持一致；

步骤S44：当解析完API的数据的时候，将相应的API的版本与分支信息保持一致，保存到数据库中。

与现有技术相比，本发明具有以下有益效果：

(1)本发明对已有项目的入侵性很小，又能解决新项目的快速接入，能够快速地推广到全行的各个系统，使各个系统都快速地使用起来；

(2)本发明开发人员不需要关注除自己本身业务代码的其他事情，开发人员只需要关注自己本身的代码层面的问题，无需额外关注跟本身代码不相关的任何事情，即可完成从源码到自动化生成API文档；

(3)本发明开发人员只需要付出较小的对接成本，只需要在对接前提供相应的代码库进行相关的配置即可；

(4)本发明生成的API文档进行集中管理，任何有权限的人员都可以在api管理系统中看到所有系统/应用的API文档，同一个口径输出API文档；

(5)本发明跟devops相结合，跟随系统/应用的源代码的更新而更新，始终保持和源码一致。

附图说明

图1为本发明一实施例的整体流程图。

图2为本发明一实施例的api管理系统解析数据流程。

具体实施方式

下面结合实施例对本发明作进一步的描述，所描述的实施例仅仅是本发明一部分实施例，并不是全部的实施例。基于本发明中的实施例，本领域的普通技术人员在没有做出创造性劳动前提下所获得的其他所用实施例，都属于本发明的保护范围。

为了更清楚地说明本说明书实施例的技术方案，下面将对实施例描述中所需要使用的附图作简单的介绍。显而易见地，下面描述中的附图仅仅是本说明书的一些示例或实施例，对于本领域的普通技术人员来讲，在不付出创造性劳动的前提下，还可以根据这些附图将本说明书应用于其它类似情景。

结合附图，本发明采用如下技术方案：

一种基于互联网金融系统从源码生成系统交互的API文档的方法。

S1:代码开发人员或者系统负责人。

步骤S11：代码开发人员或者系统负责人提交需要api管理系统的配置给api管理系统的系统管理员进行配置。

步骤S12：api管理系统的系统管理员对系统/应用的相关信息进行配置，主要包括系统/应用的名称、代码仓库、负责人，配置的目的是为了后续自动生成API文档提供前置条件。

S2:代码开发人员。

步骤S21：开发人员在接收到新的需求的时候开发代码，同时编写相应的注释，注释可以提供相应的小工具，可以一键生成，帮助开发人员生成相应的注释。

步骤S22：当代码开发完成的时候，直接提交代码到git仓库，当代码在进行code+2的时候，devpos会自动触发相应的事件，即可自动调用api管理中心的API，触发生成自动生成API文档的功能。

S3:devops整合。

步骤S31：Devops在检测到代码进行code+2的时候自动触发相应的事件，同时自己主动抓取当前系统/应用的分支信息，把当前系统/应用的所有分支信息写入到一个文件，等待api管理系统来进行拉取，为后续API版本与分支保持一致提供数据。

步骤S32：Devops在检测到代码进行code+2的时候自动触发相应的事件，调用api管理系统的相应的API。

S4:api管理系统。

步骤S41:接收当devops调用的API的时候，自动取拉取该系统的代码。

步骤S42：拉取到相应的代码的时候，检测该项目文件的完整性，主要是api管理系统需要的文件的完整性，若还需要检查其他文件是否完整，此处也可以根据需求进行设置。

步骤S43：当检测到应用的文件完整的时候，则开始解析该项目下的所有文件，只要满足文件自定义的相应注释的即进行相应的解析。

步骤S44：解析当前代码的分支，解析代码的分支的目的主要是更新API的版本，始终将API的版本与分支信息保持一致。

步骤S44：当解析完API的数据的时候，并将相应的API的版本与分支信息保持一致，保存到数据库中。

S5:静态页面展示。

步骤S51:需要查看相应的API文档，直接登录到api管理系统进行查看即可。在实际使用中，我们根据需要将最终API文档的数据进行导出，生成对外的excel和world文档。

上文已对基本概念做了描述，显然，对于本领域技术人员来说，上述详细披露仅仅作为示例，而并不构成对本说明书的限定。虽然此处并没有明确说明，本领域技术人员可能会对本说明书进行各种修改、改进和修正。该类修改、改进和修正在本说明书中被建议，所以该类修改、改进、修正仍属于本说明书示范实施例的精神和范围。

同时，本说明书使用了特定词语来描述本说明书的实施例。如“一个实施例”、“一实施例”、和/或“一些实施例”意指与本说明书至少一个实施例相关的某一特征、结构或特点。因此，应强调并注意的是，本说明书中在不同位置两次或多次提及的“一实施例”或“一个实施例”或“一个替代性实施例”并不一定是指同一实施例。此外，本说明书的一个或多个实施例中的某些特征、结构或特点可以进行适当的组合。

此外，除非权利要求中明确说明，本说明书所述处理元素和序列的顺序、数字字母的使用、或其他名称的使用，并非用于限定本说明书流程和方法的顺序。尽管上述披露中通过各种示例讨论了一些目前认为有用的发明实施例，但应当理解的是，该类细节仅起到说明的目的，附加的权利要求并不仅限于披露的实施例，相反，权利要求旨在覆盖所有符合本说明书实施例实质和范围的修正和等价组合。例如，虽然以上所描述的系统组件可以通过硬件设备实现，但是也可以只通过软件的解决方案得以实现，如在现有的服务器或移动设备上安装所描述的系统。

同理，应当注意的是，为了简化本说明书披露的表述，从而帮助对一个或多个发明实施例的理解，前文对本说明书实施例的描述中，有时会将多种特征归并至一个实施例、附图或对其的描述中。但是，这种披露方法并不意味着本说明书对象所需要的特征比权利要求中提及的特征多。实际上，实施例的特征要少于上述披露的单个实施例的全部特征。

最后，应当理解的是，本说明书中所述实施例仅用以说明本说明书实施例的原则。其他的变形也可能属于本说明书的范围。因此，作为示例而非限制，本说明书实施例的替代配置可视为与本说明书的教导一致。相应地，本说明书的实施例不仅限于本说明书明确介绍和描述的实施例。

Claims (5)

1.一种基于互联网金融系统从源码生成系统交互的API文档的方法，其特征在于，包括以下几个环节，

S1:api管理系统中进行配置环节，代码开发人员或者系统负责人在api管理系统中进行配置，对系统/应用的相关信息进行配置，为自动生成API文档提供前置条件；

S2:开发人员提交代码环节，开发人员接收需求开发代码，同时编写相应的注释，然后直接提交代码到git仓库；

S3:devops触发事件环节，代码在进行code+2的时候，devpos会自动触发相应的事件，自动调用api管理中心的API，触发生成自动生成API文档的功能；

S4:api管理系统工作环节，当devops调用的API的时候，自动取拉取该系统的代码，进行相应的解析，保存到数据库中；

S5:静态页面展示环节，需要查看相应的API文档时，登录api管理系统进行查看。

2.根据权利要求1所述的一种基于互联网金融系统从源码生成系统交互的API文档的方法，其特征在于，在S1环节中包括以下步骤，

步骤S11：代码开发人员或者系统负责人提交需要api管理系统的配置给api管理系统的系统管理员进行配置；

步骤S12：api管理系统的系统管理员对系统/应用的相关信息进行配置，包括系统/应用的名称、代码仓库、负责人，配置的目的是为了后续自动生成API文档提供前置条件。

3.根据权利要求1所述的一种基于互联网金融系统从源码生成系统交互的API文档的方法，其特征在于，在S3环节中包括以下步骤，

步骤S31：Devops在检测到代码进行code+2的时候自动触发相应的事件，同时自己主动抓取当前系统/应用的分支信息，把当前系统/应用的所有分支信息写入到一个文件，等待api管理系统来进行拉取，为后续API版本与分支保持一致提供数据。

4.根据权利要求1所述的一种基于互联网金融系统从源码生成系统交互的API文档的方法，其特征在于，在S3环节中包括以下步骤，

步骤S32：Devops在检测到代码进行code+2的时候自动触发相应的事件，调用api管理系统的相应的API，触发生成自动生成API文档的功能。

5.根据权利要求1所述的一种基于互联网金融系统从源码生成系统交互的API文档的方法，其特征在于，在S4环节中包括以下步骤，

步骤S41:接收到devops调用的API的时候，自动取拉取该系统的代码；

步骤S42：拉取到相应的代码的时候，检测该项目文件的完整性；

步骤S43：当检测到应用的文件完整的时候，则开始解析该项目下的所有文件，只要满足文件自定义的相应注释的即进行相应的解析；

步骤S44：解析当前代码的分支，更新API的版本，始终将API的版本与分支信息保持一致；

步骤S44：当解析完API的数据的时候，将相应的API的版本与分支信息保持一致，保存到数据库中。

Images