CN111258627B - 一种接口文档生成方法和装置 - Google Patents

Abstract

本发明公开了一种接口文档生成方法和装置，涉及计算机技术领域。该方法的一具体实施方式包括：接收资源定位请求，调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与资源定位请求对应的路由服务列表；通过路由服务列表中的路由信息，进行代码文档信息获取；响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与接口文档链接对应的接口文档并反馈。该实施方式可将注册中心中存储于路由信息表中的所有微服务接口文档服务统一、聚合在一个独立的页面中展示，大大提高了接口自动文档的生成查阅效率。

Description

一种接口文档生成方法和装置

技术领域

本发明涉及计算机技术领域，尤其涉及一种接口文档生成方法和装置。

背景技术

项目开发过程通常采用前后端分别开发的方式。通常做法是预先设计一份接口文档，开发人员按照该接口文档进行前后端开发。且在项目结束前需要对接口文档进行更新，以便开发人员查看并了解最新的接口定义。

目前对于接口文档的自动化生成方式，主要有：

1)基于与接口文档生成指令对应的代码生成语法树，文本分析实现和构建创新性框架和局部细节，将接口文档以word或者excel等格式进行存储；

2)通过细化开源Swagger组件，引入统一web应用开发中关于API(ApplicationProgramming Interface，应用程序接口)定义的规范，并以此作为桥梁，提升web应用前后端定义与对接API的效率。

在实现本发明的过程中，发明人发现现有技术至少存在如下问题：

方式1不支持网络和web形式的生成和展示，方式2虽可以通过浏览器查阅web阅读文档，但与方式1都局限于单台计算机节点的接口文档生成处理。

发明内容

有鉴于此，本发明实施例提供一种接口文档生成方法和装置，至少能够解决现有技术中仅局限于单台计算机节点的接口文档生成处理。

为实现上述目的，根据本发明实施例的一个方面，提供了一种接口文档生成方法，包括：

接收资源定位请求，调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表；

通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

可选的，在所述接收资源定位请求之前，还包括：

响应于对所述应用服务节点和所述网关节点的启动，判断预定表中预定字段的值是否为预定值，若是，则确定本次启动为首次启动；

调用所述网关节点中的参数配置服务，提取参数配置界面并发送至所述客户端进行显示，之后接收对所述参数配置界面中的参数输入，得到对所述网关节点的参数配置。

可选的，在所述判断预定表中预定字段的值是否为预定值之前，还包括：

将所述应用服务节点和所述网关节点在服务注册和发现节点中进行注册，以将所述应用服务节点的微服务信息和所述网关节点的微服务信息存储在所述服务注册和发现节点中。

可选的，在所述调用网关节点中的接口文档刷新服务之前，还包括：

调用所述网关节点中的安全访问服务，获取所述资源定位请求中的用户身份信息、IP地址和运行软件版本；

若所述用户身份信息中包含令牌信息，则确定所述资源定位请求的请求头包含令牌信息，对所述资源定位请求进行拦截；和/或

若在预定白名单中查询不存在所述IP地址，则对所述资源定位信息进行拦截；和/或

若所述运行软件版本的代码中不包含预定代码，则确定所述网关节点处于生产环境，对所述资源定位请求进行拦截。

可选的，所述调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表，包括：

调用所述网关节点中的路由信息监听服务，对所述服务注册和发现节点进行监听，得到刷新事件；其中，所述刷新事件为所述服务注册和发现节点在检测到所述网关节点拉取数据完毕后产生的；

调用所述接口文档刷新服务，触发所述刷新事件，读取所述服务注册和发现节点中的第一微服务列表数组、本地路由表数据库中的第二微服务和位于屏蔽名单中的第三微服务列表数组；其中，所述屏蔽名单位于所述参数配置中；

利用去重函数，对所述第一微服务列表数组、所述第二微服务列表数组和所述第三微服务列表数组进行去重操作，得到所述路由服务列表。

可选的，所述参数配置还包括预定频繁时间段和与所述预定频繁时间段对应的第一预定数量、预定休息时间段和与所述预定休息时间段对应的第二预定数量；

所述调用所述接口文档刷新服务，触发所述刷新事件，包括：

获取当前时间点，若所述当前时间点处于所述预定频繁时间段内、且累计的刷新事件数量大于或等于所述第一预定数量，则调用所述接口文档刷新服务，触发所述刷新事件；或

若所述当前时间点处于所述预定休息时间段内、且累计的刷新事件数量大于或等于所述第二预定数量，则调用所述接口文档刷新服务，触发所述刷新事件。

为实现上述目的，根据本发明实施例的另一方面，提供了一种接口文档生成装置，包括：

信息聚合模块，用于接收资源定位请求，调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表；

信息获取模块，用于通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

文档生成模块，用于响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

可选的，还包括参数配置模块，用于：

响应于对所述应用服务节点和所述网关节点的启动，判断预定表中预定字段的值是否为预定值，若是，则确定本次启动为首次启动；

调用所述网关节点中的参数配置服务，提取参数配置界面并发送至所述客户端进行显示，之后接收对所述参数配置界面中的参数输入，得到对所述网关节点的参数配置。

可选的，还包括微服务注册模块，用于：

将所述应用服务节点和所述网关节点在服务注册和发现节点中进行注册，以将所述应用服务节点的微服务信息和所述网关节点的微服务信息存储在所述服务注册和发现节点中。

可选的，所述信息聚合模块，还用于：

调用所述网关节点中的安全访问服务，获取所述资源定位请求中的用户身份信息、IP地址和运行软件版本；

若所述用户身份信息中包含令牌信息，则确定所述资源定位请求的请求头包含令牌信息，对所述资源定位请求进行拦截；和/或

若在预定白名单中查询不存在所述IP地址，则对所述资源定位信息进行拦截；和/或

若所述运行软件版本的代码中不包含预定代码，则确定所述网关节点处于生产环境，对所述资源定位请求进行拦截。

可选的，所述信息聚合模块，用于：

调用所述网关节点中的路由信息监听服务，对所述服务注册和发现节点进行监听，得到刷新事件；其中，所述刷新事件为所述服务注册和发现节点在检测到所述网关节点拉取数据完毕后产生的；

调用所述接口文档刷新服务，触发所述刷新事件，读取所述服务注册和发现节点中的第一微服务列表数组、本地路由表数据库中的第二微服务和位于屏蔽名单中的第三微服务列表数组；其中，所述屏蔽名单位于所述参数配置中；

利用去重函数，对所述第一微服务列表数组、所述第二微服务列表数组和所述第三微服务列表数组进行去重操作，得到所述路由服务列表。

可选的，所述参数配置还包括预定频繁时间段和与所述预定频繁时间段对应的第一预定数量、预定休息时间段和与所述预定休息时间段对应的第二预定数量；

所述信息聚合模块，用于：

获取当前时间点，若所述当前时间点处于所述预定频繁时间段内、且累计的刷新事件数量大于或等于所述第一预定数量，则调用所述接口文档刷新服务，触发所述刷新事件；或

若所述当前时间点处于所述预定休息时间段内、且累计的刷新事件数量大于或等于所述第二预定数量，则调用所述接口文档刷新服务，触发所述刷新事件。

为实现上述目的，根据本发明实施例的再一方面，提供了一种接口文档生成电子设备。

本发明实施例的电子设备包括：一个或多个处理器；存储装置，用于存储一个或多个程序，当所述一个或多个程序被所述一个或多个处理器执行，使得所述一个或多个处理器实现上述任一所述的接口文档生成方法。

为实现上述目的，根据本发明实施例的再一方面，提供了一种计算机可读介质，其上存储有计算机程序，所述程序被处理器执行时实现上述任一所述的接口文档生成方法。

根据本发明所述提供的方案，上述发明中的一个实施例具有如下优点或有益效果：设置AHPARSRI算法，可以实时获取所有的、可探测发现的分布式节点接口文档的服务地址列表，并通过接口文档服务智能聚合模块将分布式分散在应用服务器各节点的接口相关信息聚合在一起，解决了现有单个节点需要提供独立访问的网页web接口文档地址的低效、分散不便利的问题。

上述的非惯用的可选方式所具有的进一步效果将在下文中结合具体实施方式加以说明。

附图说明

附图用于更好地理解本发明，不构成对本发明的不当限定。其中：

图1是节点拓扑示意图；

图2是节点之间的连接框架示意图；

图3是根据本发明实施例的一种接口文档生成方法的流程示意图；

图4是根据本发明实施例的一种可选的接口文档生成方法的流程示意图；

图5是根据本发明实施例的另一种可选的接口文档生成方法的流程示意图；

图6是根据本发明实施例的又一种可选的接口文档生成方法的流程示意图；

图7是根据本发明实施例的一种具体地接口文档生成方法的流程示意图；

图8是根据本发明实施例的一种接口文档生成装置的主要模块示意图；

图9是本发明实施例可以应用于其中的示例性系统架构图；

图10是适于用来实现本发明实施例的移动设备或服务器的计算机系统的结构示意图。

具体实施方式

以下结合附图对本发明的示范性实施例做出说明，其中包括本发明实施例的各种细节以助于理解，应当将它们认为仅仅是示范性的。因此，本领域普通技术人员应当认识到，可以对这里描述的实施例做出各种改变和修改，而不会背离本发明的范围和精神。同样，为了清楚和简明，以下的描述中省略了对公知功能和结构的描述。

对于本发明所涉及的词语，做解释如下：

API：是一些预先定义的函数或指软件系统不同组成部分衔接的约定，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问原码或理解内部工作机制的细节。

微服务：一种将单应用程序作为一套小型服务开发的方法，每种应用程序都在其进程中运行，并与轻量级机制(通常是http资源的API)进行通信。

springcloud框架：一整套微服务的解决方案，包括服务注册与发现、配置中心、全链路监控、服务网关、负载均衡、熔断器等组件。

本发明涉及节点数量众多，为简便起见，对节点类型统一命名：

1)将服务注册和发现节点，命名为节点A；对应节点A部署服务命名为serviceA；

2)将应用服务节点，分别命名为节点serverB1、serverB2、serverB3；上述节点中的服务分别命名为serviceB1、serviceB2、serivceB3；

3)将网关服务节点，命名为节点C；对应节点C部署的服务命名为serviceC；

上述节点拓扑图，详见附图1所示。

对于节点C，核心服务包括但不限于：

S003节点C参数配置模块

S004节点C接口文档服务智能刷新模块

S005节点C网关路由消息监听模块

S006节点C安全访问模块

S007节点C接口文档服务智能聚合模块

其与S001节点A服务注册和发现模块、S002节点B接口文档生成模块之间的连接框架，参见图2所示。

参见图3，示出的是本发明实施例提供的一种接口文档生成方法的主要流程图，包括如下步骤：

S301：接收资源定位请求，调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表；

S302：通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

S303：响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

上述实施方式中，对于步骤S301，本发明以浏览器客户端中用户点击地址生成的请求URL(Uniform Resource Locator，统一资源定位符)为例，假设URL地址为：

http://xxx-gateway-host:8077/swagger-ui.html

为便于后续描述，将该请求统一命名为requst_api_document，其代表一个请求的URL地址，用户使用requst_api_document地址封装为一个http请求。

requst_api_document向网关节点C发送一个http请求，假若requst_api_document通过了S006节点C安全访问模块(参见后续图4所示描述，在此不再赘述)，该请求会获取S007节点C接口文档服务智能聚合模块中的数据。

S007节点C接口文档服务智能聚合模块，首先会调用S004节点C接口文档服务智能刷新模块，将分布式分散在应用服务器各节点的接口相关信息聚合在一起，得到与URL地址对应的路由服务列表，包含各个服务节点的数据信息。

需要说明的是，该刷新服务是将节点状态拉取到聚合文档的关键和核心所在。在一个集群里的节点，由于偶然或不可知的因素，时刻都可能有节点宕机，或者由于容量扩充冗余备份需要有新节点加入，这些问题都需要实时动态了解注册节点的整体情况。若不做刷新，引发宕机和新加入的节点都没有更新问题，最终导致路由数据不准确。

对于步骤S302，S007节点C接口文档服务智能聚合模块，通过上述所得路由服务列表中的路由信息，获取对应的代码文档信息，其中代码文档信息包含但不限于节点接口文档链接，例如针对应用服务器serverB1、serverB2、serverB3其具体接口文档地址为：

http://xxx-serverB1-host:8077/swagger-ui.html

http://xxx-serverB2-host:8077/swagger-ui.html

http://xxx-serverB3-host:8077/swagger-ui.html

对于步骤S303，通过在网关的swagger界面，点击上述接口文档中的任意一个，获取分布式节点的接口文档数据。例如选择serverB1对应的标签，此时会发起http://xxx-serverB1-host:8077/swagger-ui.html获取页面相关数据的请求信息。此处的请求则直接调用S002节点B接口文档生成模块，获取对应的接口文档生成信息。

以节点B1为例，属于节点B1对应服务serviceB1的一个核心模块，该模块一般会随着节点B1中的应用服务serviceB1启动而加载。该模块会对节点B应用服务serviceB1的字节码进行扫描，进而发现满足接口文档生产标记的函数和方法，同时将对应方法的参数和描述信息，保存到指定的内存缓存中。后续获取请求服务的时候，serviceB1相关的接口文档信息可以从缓冲中读取，并通过http请求返回给请求的客户端。

需要说明的是，本发明仅需要在页面中输入一次请求，即可聚合所有接口文档信息。例如一个集群中有100台设备，现有方案需要输入100次，而本发明只需一次即可。并且随着集群设备动态的增加、宕机等，所得路由服务列表中的数据还可以随之动态变化，解决了常规接口文档生成模块不能解决的分布式问题。

上述实施例所提供的方法，仅需一次请求，即可将注册中心中存储于路由信息表中的所有微服务接口文档服务统一、聚合在一个独立的页面中展示，大大提高了接口自动文档的生成查阅效率。

参见图4，示出了根据本发明实施例的一种可选的接口文档生成方法流程示意图，包括如下步骤：

S401：响应于对应用服务节点和网关节点的启动，将应用服务节点和网关节点在服务注册和发现节点中进行注册，以将应用服务节点的微服务信息和网关节点的微服务信息存储在所述服务注册和发现节点中；

S402：判断预定表中预定字段的值是否为预定值，若是，则确定本次启动为首次启动；

S403：调用所述网关节点中的参数配置服务，提取参数配置界面并发送至所述客户端进行显示，之后接收对所述参数配置界面中的参数输入，得到对所述网关节点的参数配置；

S404：接收资源定位请求，调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表；

S405：通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

S406：响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

上述实施方式中，对于步骤S403～S405可参见图3所示步骤S301～S303的描述，在此不再赘述。

上述实施方式中，对于步骤S401，系统管理员依次开启节点A、节点B、节点C各项核心服务。

节点A和节点B的初始化，主要包含S001节点A服务注册和发现模块的启动和初始化、S002节点B接口文档生成模块的启动和初始化：

S001节点A服务注册和发现模块，属于节点A的启动的注册和发现微服务serviceA，是一个独立的、与应用层业务代码分离的组件，存在服务注册和发现服务或模块的开源实现，如eureka、zookeeper、nacos等。以在开源的springcloud微服务中依赖eureka组件为例，在微服务springcloud配置文件增加类似的引用：

<dependency>

<groupId>org.springframework.cloud</groupId>

<artifactId>spring-cloud-starter-eureka-server</artifactId>

</dependency>

即可使用对应的服务注册和发现组件。

S002节点B接口文档生成模块，是一个独立的、与应用层业务代码分离的组件，存在成熟的接口文档自动生成模块或实现，如swagger等。以在开源的springcloud微服务中依赖swagger组件为例，在应用微服务serviceB1、serviceB2、serviceB2各服务的springcloud配置文件分别增加类似的代码引用：

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger2</artifactId>

<version>2.6.1</version>

</dependency>

<dependency>

<groupId>io.springfox</groupId>

<artifactId>springfox-swagger-ui</artifactId>

<version>2.6.1</version>

</dependency>

即可使用对应的接口文档生成组件。

需要说明的是，以上S001节点A服务注册和发现模块、S002节点B接口文档生成模块属于公知常识，在工业界也有有成熟的开源实现。本发明在上述两个模块中不做或仅做少量工程优化，不会做大的理论和方法上的创新，因此仅如上描述其大概原理，在此不赘述其工程实现细节。

系统服务启动可以通过多种形式触发，软件实现上的一种可用方案一般是运行一个批处理脚本，该脚本有一段可执行的命令行代码，包含上述启动流程。

应用服务serviceB1-serviceB3、网关节点C的服务serviceC等在启动时，均会向节点A的服务serviceA。节点A服务注册表中将会存储所有可用服务节点的信息，从而已注册的各类服务和serviceA可以互相识别。

该注册时机通常为系统启动时，所有节点都需要向节点A该主机地址发起注册请求，并登记其可提供的服务，将主机与端口号、版本号、通讯协议等一些附加信息告知注册中心。

注册中心按照服务名分类组织服务清单，并以心跳方式监控清单中各个节点是否可用，若不可用则需要从服务清单中剔除，达到排除故障服务的效果。在服务治理框架下运行，服务间的调用不再通过指定具体的实例地址来实现，而是通过向服务名发起请求调用。

对于步骤S402，首次启动的另外之处在于参数配置初始化，对于本次启动是否为首次的判断方式，具体地，可以在数据库中建立一张表，例如first_init表，并设有字段first_boot(默认为0)，首次启动时需要将其修改为1，以便在后续第二次、第三次启动时通过判断first_init.first_boot的值是否为0来决定是否需要执行参数配置这一操作。

对于步骤S403，对于节点C的初始化，核心服务包括但不限于：

S004节点C接口文档服务智能刷新启动及初始化；

S005节点C网关路由消息队列启动和初始化；

S006节点C安全访问模块启动和初始化；

S007节点C接口文档服务智能聚合模块启动和初始化等。

对于首次启动，需要在S003节点C参数配置模块进行相关参数配置，系统管理员可以通过预设界面进行参数输入：

n_busy＝1；

n_idle＝100；

discover_list_blacklist＝[secret_token_service]；

其中，n_busy和n_idle表示触发阈值。以n_busy为例，表示频繁时间段内的刷新事件数量大于等于该值时heartbeatEventCnt>＝n_busy，触发对应的逻辑(如刷新事件)，具体参见后续图6所示描述。

上述实施例所提供的方法，在系统启动并初始化时，通过判断其预定字段的值是否为预设值，以此决定是否需要执行参数配置这一操作，为后续刷新事件的执行逻辑提供参数逻辑。

参见图5，示出了根据本发明实施例的另一种可选的接口文档生成方法流程示意图，包括如下步骤：

S501：接收资源定位请求，调用所述网关节点中的安全访问服务，获取所述资源定位请求中的用户身份信息、IP地址和运行软件版本；

S502：若所述用户身份信息中包含令牌信息，则确定所述资源定位请求的请求头包含令牌信息，对所述资源定位请求进行拦截；

S503：若在预定白名单中查询不存在所述IP地址，则对所述资源定位信息进行拦截；

S504：若所述运行软件版本的代码中不包含预定代码，则确定所述网关节点处于生产环境，对所述资源定位请求进行拦截；

S505：调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表；

S506：通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

S507：响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

上述实施方式中，对于步骤S505～S507，可参见图3所示步骤S301～S303的描述，在此不再赘述。

上述实施方式中，对于步骤S501～S504，网关节点C在收到客户端传输的http请求后，会先调用S006节点C安全访问模块判定当前请求是否安全。

S006节点C安全访问模块，其安全策略会对http请求中的信息进行安全校验和过滤，包括但不限于用户身份识别、请求IP识别、运行软件版本智能识别等，最终确认请求是否需要拦截、重定向、准入或拒绝：

1)对于用户身份识别，包含一个请求登录态的判断，识别当前请求中的用户请求头是否包含token信息，若包含，则进行拦截；其中，token在计算机身份认证中是令牌(临时)的意思，一般作为邀请、登录系统使用。

2)对于IP地址识别，会对指定的白名单内的请求进行正确响应，对于不包含在白名单中的请求则不予通过或拒绝访问。

3)对于运行软件版本智能识别，包含对当前节点C是生产环境还是测试环境的判断。若是生产环境，则该请求不响应对应的信息，用以确保生产环境的安全；但若是测试环境，则对上述http请求予以准入。

微服务springcloud框架可以针对服务本身的profile进行智能动态识别和判断。运行的微服务在配置文件中的一个配置项activeprofile，其在生产环境的设备上配置的是prod，本地和测试环境是local或者dev，所以配置dev/local的时候，上述设置生效，予以准入，生产环境配置prod时会对上述http请求进行拦截进而确保安全。

上述运行软件版本动态识别的工程实现，可选方案之一，是对加载或者注入的代码进行加载范围限定，例如，在应用微服务B1、B2、B3和C的代码中，都增加如下的限定：

对于生产环境，其@Profile({"local","dev"})注解标签里中没有prod，因此该环境内的http请求是无法拉取到对应信息，以此实现自动拦截；但对于测试环境和本地环境可以确保请求准入。

上述实施例所提供的方法，对于http请求的处理需要在判断其安全的基础上进行，且判断依据包括但不限于用户身份识别、请求IP识别、运行软件版本智能识别，以此确保系统安全。

参见图6，示出了根据本发明实施例的又一种可选的接口文档生成方法流程示意图，包括如下步骤：

S601：接收资源定位请求，调用所述网关节点中的路由信息监听服务，对所述服务注册和发现节点进行监听，得到刷新事件；其中，所述刷新事件为所述服务注册和发现节点在检测到所述网关节点拉取数据完毕后产生的；

S602：调用所述接口文档刷新服务，触发所述刷新事件，读取所述服务注册和发现节点中的第一微服务列表数组、本地路由表数据库中的第二微服务和位于屏蔽名单中的第三微服务列表数组；其中，所述屏蔽名单位于所述参数配置中；

S603：利用去重函数，对所述第一微服务列表数组、所述第二微服务列表数组和所述第三微服务列表数组进行去重操作，得到所述路由服务列表；

S604：通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

S605：响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

上述实施方式中，对于步骤S604、S605可参见图3所示步骤S302和S303的描述，在此不再赘述。

上述实施方式中，对于步骤S601，S004节点C接口文档服务智能刷新模块，包含手动刷新和自动刷新两种模式：

1)手动刷新是指点击页面的按钮，触发对应的刷新服务，使得新增的应用服务能够被注册节点和网关节点发现；

2)自动刷新则表示通过某种自动刷新策略，例如定时策略，使得新增的应用服务能够被注册节点和网关节点发现。

在本发明中，将上述两种方法融合起来并增加部分优化和创新细节，称之为AHPARSRI算法(Adaptive HybridPassive and Auto Refresh Strategy for RouteInformation，手动和自动刷新融合的自适应路由信息刷新算法)，简称刷新算法。

网关服务serviceC的S005节点C网关路由消息监听模块，监听来自S001节点A服务注册和发现模块的刷新事件；且S005节点C可以监听各种与路由表相关的事件，并对相应事件进行处理。例如，对自动模式的heartbeatEvent或者手动模式的PassiveRefreshEvent等事件进行累计，超过阈值进行事件传递等流程。

网关服务serviceC如前述描述，也注册在S001节点A服务注册和发现模块上。serviceC按照eureka心跳服务配置，每间隔一定时间(30秒到几分钟不等)会去serviceA上拉取数据，并在拉取数据完毕后，serviceA会发出刷新事件heartbeatEvent。

需要说明的是，考虑节点刷新操作，为保证节点C保存的服务列表中不会出现信息不全甚至错误的问题，需要每隔一定时间从serviceA中拉取数据。这些数据是节点A中注册的服务清单列表；上述清单列表具体包含的信息有：服务serviceC、serviceB1-serviceB3的主机与端口号、版本号、通信协议等一些附加信息。存在微服务框架提供配置参数eureka.client.registry-fetch-interval-seconds，该参数通过指定特有的时间间隔，用以告知serviceC从节点serviceA拉取服务清单数据的数据拉取的时间周期。

对于步骤S602和S603，网关服务通过S005节点C网关路由消息监听模块获取当前刷新事件heartbeatEvent，获取当前时间点，判断当前时间点是否处于频繁使用的工作时间段，同样，该时间段可以由工作人员设定。

例如频繁时间段time_work＝[8:00-18:00]，则对累计刷新事件的数量，得到heartbeatEventCnt，若满足heartbeatEventCnt>＝n_busy，则执行路由服务列表刷新动作，且触发刷新以后将heartbeatEventCnt数值清零；

若为休息事件段，即频繁时间段time_work以外的休息时间time_idle＝[18:00-24:00,0:00-8:00](也可以为其他时间段)，则同样需累计刷新事件数量，得到heartbeatEventCnt，若满足heartbeatEventCnt>＝n_idle，则执行路由服务列表刷新工作，且刷新以后将heartbeatEventCnt数值清零。

手动刷新模式，主要指的是同时提供一个微服务调用接口，对上述服务列表刷新操作通过页面点击进行刷新；

自动刷新模式，会将生成PassiveRefreshEvent事件，通过消息队列发送到节点C的S005节点C网关路由消息监听模块，进而执行手动刷新操作；

上述路由服务列表刷新的结果，称之为discover_list_refresh。

本发明的刷新策略为对若干数据的集合逻辑运算，自定义uniq()函数，为对列表数据去重的函数，目的是使得列表中数据不会重复：

discover_list_refresh＝uniq(discover_list_eureka+discover_list_db-discover_list_blacklist)；

其中，刷新算法会主动读取上述discover_list_eureka，discover_list_db，discover_list_blacklist列表数据信息：

1)discover_list_eureka为服务节点A中的微服务列表数组；

2)discover_list_db为路由表数据库的微服务；是预设在本地路由数据库中的数据库路由信息表，通过在刷新策略触发的时候，读取上述路由本地数据库，加载到内存中得到的列表数组；

3)discover_list_blacklist为黑名单或者敏感、涉密等需要屏蔽的微服务列表数组。

需要说明的是，以上discover_list_***都是包含微服务信息的列表数组，每个数组的元素是某个服务的主机与端口号、版本号、通信协议等一些附加信息。

通过AHPARSRI算法可以使得：

1)在工作繁忙时间，自动将最近或者刚刚部署的微服务增加到路由信息表里面去，使得路由表数据得到及时、完整的刷新，同时通过剔除敏感涉密的微服务，使得接口保密和安全得到了保障；

2)在非工作时段，通过增大累计阈值增大刷新数据的间隔，减少频繁更新数据库和路由表数据的操作，降低了服务器资源的损耗；

3)提供手动刷新模式，补充和完善了路由信息刷新的一般场景。

上述实施例所提供的方法，基于不同时间段设置有不同的触发刷新事件逻辑，以自动适应性更新数据库和路由表数据，保证路由表数据得到及时、完整的刷新，同时提出敏感涉密微服务，使得接口保密和安全得到了保障。

参见图7，示出了根据本发明实施例的一具体地接口文档生成方法流程示意图，包括如下步骤：

S701：响应于对应用服务节点和网关节点的启动，将应用服务节点和网关节点在服务注册和发现节点中进行注册，以将应用服务节点的微服务信息和网关节点的微服务信息存储在所述服务注册和发现节点中；

S702：判断预定表中预定字段的值是否为预定值，若是，则确定本次启动为首次启动；

S703：调用所述网关节点中的参数配置服务，提取参数配置界面并发送至所述客户端进行显示，之后接收对所述参数配置界面中的参数输入，得到对所述网关节点的参数配置；

S704：接收资源定位请求，调用所述网关节点中的安全访问服务，获取所述资源定位请求中的用户身份信息、IP地址和运行软件版本；

S705：若用户身份信息中包含令牌信息，则确定资源定位请求的请求头包含令牌信息，对资源定位请求进行拦截；

S706：若在预定白名单中查询不存在所述IP地址，则对所述资源定位信息进行拦截；

S707：若所述运行软件版本的代码中不包含预定代码，则确定所述网关节点处于生产环境，对所述资源定位请求进行拦截；

S708：调用所述网关节点中的路由信息监听服务，对所述服务注册和发现节点进行监听，得到刷新事件；其中，所述刷新事件为所述服务注册和发现节点在检测到所述网关节点拉取数据完毕后产生的；

S709：调用所述接口文档刷新服务，触发所述刷新事件，读取所述服务注册和发现节点中的第一微服务列表数组、本地路由表数据库中的第二微服务和位于屏蔽名单中的第三微服务列表数组；其中，所述屏蔽名单位于所述参数配置中；

S710：利用去重函数，对所述第一微服务列表数组、所述第二微服务列表数组和所述第三微服务列表数组进行去重操作，得到所述路由服务列表；

S711：通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

S712：响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

对于单节点接口自动生成工具，除了上述提到的swagger组件，还可以使用开源的apidoc组件；apidoc方案在单节点使用方面与swagger类似；但是apidoc本身基于nodejs开源框架，需要额外的软件和服务部署开销，并且apidoc本身只提供接口文档功能，swagger除了接口文档外，还包含协助人员对接口进行接口测试的额外附加功能。

在分布式环境部署和统一入口查阅方面，apidoc实现没有swagger开源组件容易；在实际的工程运用，尤其是springcloud微服务后台项目中，swagger已经替代apidoc成为主流的接口文档生成工具之一，因此本发明主要使用swagger组件。

本发明实施例所提供的方法，相对于现有技术，至少存在如下有益效果：

1)在工作繁忙时间段，自动将最近或者刚刚部署的微服务增加到路由信息表中，使得路由表数据得到及时完整的刷新，同时通过剔除敏感涉密的微服务，使得接口保密和安全得到了保障；

在非工作时段，通过增大累计阈值增大刷新数据的间隔，减少频繁更新数据库和路由表数据的操作，降低了服务器资源的损耗；同时提供的手动刷新模式，补充和完善了路由信息刷新的一般场景；

2)设置AHPARSRI算法，可以实时获取所有的、可探测发现的分布式节点接口文档的服务地址列表，并通过接口文档服务智能聚合模块将分布式分散在应用服务器各节点的接口相关信息聚合在一起；

3)解决了现有单个节点需要提供独立访问的网页web接口文档地址的低效、分散不便利的问题；

4)通过提供分布式集群所有节点的接口文档生成和聚合的统一web访问入口，规范和统一化了接口文档的管理，确保了其实时性、高效性和安全性，方便了工作人员对接口的查阅和项目中长期远景规划，大大提升了项目研发的效率。

参见图8，示出了本发明实施例提供的一种接口文档生成装置800的主要模块示意图，包括：

信息聚合模块801，用于接收资源定位请求，调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表；

信息获取模块802，用于通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

文档生成模块803，用于响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

本发明实施装置还包括参数配置模块804(图中未标出)，用于：

响应于对所述应用服务节点和所述网关节点的启动，判断预定表中预定字段的值是否为预定值，若是，则确定本次启动为首次启动；

调用所述网关节点中的参数配置服务，提取参数配置界面并发送至所述客户端进行显示，之后接收对所述参数配置界面中的参数输入，得到对所述网关节点的参数配置。

本发明实施装置还包括微服务注册模块805(图中未标出)，用于：将所述应用服务节点和所述网关节点在服务注册和发现节点中进行注册，以将所述应用服务节点的微服务信息和所述网关节点的微服务信息存储在所述服务注册和发现节点中。

本发明实施装置中，所述信息聚合模块801，还用于：

调用所述网关节点中的安全访问服务，获取所述资源定位请求中的用户身份信息、IP地址和运行软件版本；

若所述用户身份信息中包含令牌信息，则确定所述资源定位请求的请求头包含令牌信息，对所述资源定位请求进行拦截；和/或

若在预定白名单中查询不存在所述IP地址，则对所述资源定位信息进行拦截；和/或

若所述运行软件版本的代码中不包含预定代码，则确定所述网关节点处于生产环境，对所述资源定位请求进行拦截。

本发明实施装置中，所述信息聚合模块801，用于：

调用所述网关节点中的路由信息监听服务，对所述服务注册和发现节点进行监听，得到刷新事件；其中，所述刷新事件为所述服务注册和发现节点在检测到所述网关节点拉取数据完毕后产生的；

调用所述接口文档刷新服务，触发所述刷新事件，读取所述服务注册和发现节点中的第一微服务列表数组、本地路由表数据库中的第二微服务和位于屏蔽名单中的第三微服务列表数组；其中，所述屏蔽名单位于所述参数配置中；

利用去重函数，对所述第一微服务列表数组、所述第二微服务列表数组和所述第三微服务列表数组进行去重操作，得到所述路由服务列表。

本发明实施装置中，所述参数配置还包括预定频繁时间段和与所述预定频繁时间段对应的第一预定数量、预定休息时间段和与所述预定休息时间段对应的第二预定数量；

所述信息聚合模块801，用于：

获取当前时间点，若所述当前时间点处于所述预定频繁时间段内、且累计的刷新事件数量大于或等于所述第一预定数量，则调用所述接口文档刷新服务，触发所述刷新事件；或

若所述当前时间点处于所述预定休息时间段内、且累计的刷新事件数量大于或等于所述第二预定数量，则调用所述接口文档刷新服务，触发所述刷新事件。

另外，在本发明实施例中所述装置的具体实施内容，在上面所述方法中已经详细说明了，故在此重复内容不再说明。

图9示出了可以应用本发明实施例的示例性系统架构900。

如图9所示，系统架构900可以包括终端设备901、902、903，网络904和服务器905(仅仅是示例)。网络904用以在终端设备901、902、903和服务器905之间提供通信链路的介质。网络904可以包括各种连接类型，例如有线、无线通信链路或者光纤电缆等等。

用户可以使用终端设备901、902、903通过网络904与服务器905交互，以接收或发送消息等。终端设备901、902、903上可以安装有各种通讯客户端应用。

终端设备901、902、903可以是具有显示屏并且支持网页浏览的各种电子设备，包括但不限于智能手机、平板电脑、膝上型便携计算机和台式计算机等等。

服务器905可以是提供各种服务的服务器，例如对用户利用终端设备901、902、903所浏览的购物类网站提供支持的后台管理服务器(仅为示例)。

需要说明的是，本发明实施例所提供的方法一般由服务器905执行，相应地，装置一般设置于服务器905中。

应该理解，图9中的终端设备、网络和服务器的数目仅仅是示意性的。根据实现需要，可以具有任意数目的终端设备、网络和服务器。

下面参考图10，其示出了适于用来实现本发明实施例的终端设备的计算机系统1000的结构示意图。图10示出的终端设备仅仅是一个示例，不应对本发明实施例的功能和使用范围带来任何限制。

如图10所示，计算机系统1000包括中央处理单元(CPU)1001，其可以根据存储在只读存储器(ROM)1002中的程序或者从存储部分1008加载到随机访问存储器(RAM)1003中的程序而执行各种适当的动作和处理。在RAM 1003中，还存储有系统1000操作所需的各种程序和数据。CPU 1001、ROM 1002以及RAM 1003通过总线1004彼此相连。输入/输出(I/O)接口1005也连接至总线1004。

以下部件连接至I/O接口1005：包括键盘、鼠标等的输入部分1006；包括诸如阴极射线管(CRT)、液晶显示器(LCD)等以及扬声器等的输出部分1007；包括硬盘等的存储部分1008；以及包括诸如LAN卡、调制解调器等的网络接口卡的通信部分1009。通信部分1009经由诸如因特网的网络执行通信处理。驱动器1010也根据需要连接至I/O接口1005。可拆卸介质1011，诸如磁盘、光盘、磁光盘、半导体存储器等等，根据需要安装在驱动器1010上，以便于从其上读出的计算机程序根据需要被安装入存储部分1008。

特别地，根据本发明公开的实施例，上文参考流程图描述的过程可以被实现为计算机软件程序。例如，本发明公开的实施例包括一种计算机程序产品，其包括承载在计算机可读介质上的计算机程序，该计算机程序包含用于执行流程图所示的方法的程序代码。在这样的实施例中，该计算机程序可以通过通信部分1009从网络上被下载和安装，和/或从可拆卸介质1011被安装。在该计算机程序被中央处理单元(CPU)1001执行时，执行本发明的系统中限定的上述功能。

需要说明的是，本发明所示的计算机可读介质可以是计算机可读信号介质或者计算机可读存储介质或者是上述两者的任意组合。计算机可读存储介质例如可以是——但不限于——电、磁、光、电磁、红外线、或半导体的系统、装置或器件，或者任意以上的组合。计算机可读存储介质的更具体的例子可以包括但不限于：具有一个或多个导线的电连接、便携式计算机磁盘、硬盘、随机访问存储器(RAM)、只读存储器(ROM)、可擦式可编程只读存储器(EPROM或闪存)、光纤、便携式紧凑磁盘只读存储器(CD-ROM)、光存储器件、磁存储器件、或者上述的任意合适的组合。在本发明中，计算机可读存储介质可以是任何包含或存储程序的有形介质，该程序可以被指令执行系统、装置或者器件使用或者与其结合使用。而在本发明中，计算机可读的信号介质可以包括在基带中或者作为载波一部分传播的数据信号，其中承载了计算机可读的程序代码。这种传播的数据信号可以采用多种形式，包括但不限于电磁信号、光信号或上述的任意合适的组合。计算机可读的信号介质还可以是计算机可读存储介质以外的任何计算机可读介质，该计算机可读介质可以发送、传播或者传输用于由指令执行系统、装置或者器件使用或者与其结合使用的程序。计算机可读介质上包含的程序代码可以用任何适当的介质传输，包括但不限于：无线、电线、光缆、RF等等，或者上述的任意合适的组合。

附图中的流程图和框图，图示了按照本发明各种实施例的系统、方法和计算机程序产品的可能实现的体系架构、功能和操作。在这点上，流程图或框图中的每个方框可以代表一个模块、程序段、或代码的一部分，上述模块、程序段、或代码的一部分包含一个或多个用于实现规定的逻辑功能的可执行指令。也应当注意，在有些作为替换的实现中，方框中所标注的功能也可以以不同于附图中所标注的顺序发生。例如，两个接连地表示的方框实际上可以基本并行地执行，它们有时也可以按相反的顺序执行，这依所涉及的功能而定。也要注意的是，框图或流程图中的每个方框、以及框图或流程图中的方框的组合，可以用执行规定的功能或操作的专用的基于硬件的系统来实现，或者可以用专用硬件与计算机指令的组合来实现。

描述于本发明实施例中所涉及到的模块可以通过软件的方式实现，也可以通过硬件的方式来实现。所描述的模块也可以设置在处理器中，例如，可以描述为：一种处理器包括信息聚合模块、信息获取模块、文档生成模块。其中，这些模块的名称在某种情况下并不构成对该模块本身的限定，例如，文档生成模块还可以被描述为“生成接口文档的模块”。

作为另一方面，本发明还提供了一种计算机可读介质，该计算机可读介质可以是上述实施例中描述的设备中所包含的；也可以是单独存在，而未装配入该设备中。上述计算机可读介质承载有一个或者多个程序，当上述一个或者多个程序被一个该设备执行时，使得该设备包括：

接收资源定位请求，调用网关节点中的接口文档刷新服务，对各节点的接口信息进行聚合，得到与所述资源定位请求对应的路由服务列表；

通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

根据本发明实施例的技术方案，相对于现有技术，至少存在如下有益效果：

1)在工作繁忙时间段，自动将最近或者刚刚部署的微服务增加到路由信息表中，使得路由表数据得到及时完整的刷新，同时通过剔除敏感涉密的微服务，使得接口保密和安全得到了保障；

在非工作时段，通过增大累计阈值增大刷新数据的间隔，减少频繁更新数据库和路由表数据的操作，降低了服务器资源的损耗；同时提供的手动刷新模式，补充和完善了路由信息刷新的一般场景；

2)设置AHPARSRI算法，可以实时获取所有的、可探测发现的分布式节点接口文档的服务地址列表，并通过接口文档服务智能聚合模块将分布式分散在应用服务器各节点的接口相关信息聚合在一起；

3)解决了现有单个节点需要提供独立访问的网页web接口文档地址的低效、分散不便利的问题；

4)通过提供分布式集群所有节点的接口文档生成和聚合的统一web访问入口，规范和统一化了接口文档的管理，确保了其实时性、高效性和安全性，方便了工作人员对接口的查阅和项目中长期远景规划，大大提升了项目研发的效率。

上述具体实施方式，并不构成对本发明保护范围的限制。本领域技术人员应该明白的是，取决于设计要求和其他因素，可以发生各种各样的修改、组合、子组合和替代。任何在本发明的精神和原则之内所作的修改、等同替换和改进等，均应包含在本发明保护范围之内。

Claims (8)

1.一种接口文档生成方法，其特征在于，包括：

接收用户点击地址生成的资源定位请求，在所述资源定位请求通过网关节点安全访问服务的情况下，调用网关节点中的路由信息监听服务，对服务注册和发现节点进行监听，得到刷新事件；其中，所述刷新事件为所述服务注册和发现节点在检测到所述网关节点拉取数据完毕后产生的；

调用接口文档刷新服务，触发所述刷新事件，读取所述服务注册和发现节点中的第一微服务列表数组、本地路由表数据库中的第二微服务列表数组和位于屏蔽名单中的第三微服务列表数组；其中，所述屏蔽名单位于参数配置中；

利用去重函数，对所述第一微服务列表数组、所述第二微服务列表数组和所述第三微服务列表数组进行去重操作，得到路由服务列表；其中，路由服务列表包括各个服务节点的路由信息；

通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

2.根据权利要求1所述的方法，其特征在于，在所述接收用户点击地址生成的资源定位请求之前，还包括：

响应于对所述应用服务节点和所述网关节点的启动，判断预定表中预定字段的值是否为预定值，若是，则确定本次启动为首次启动；

调用所述网关节点中的参数配置服务，提取参数配置界面并发送至客户端进行显示，之后接收对所述参数配置界面中的参数输入，得到对所述网关节点的参数配置。

3.根据权利要求2所述的方法，其特征在于，在所述资源定位请求通过网关节点安全访问服务的情况下，还包括：

将所述应用服务节点和所述网关节点在服务注册和发现节点中进行注册，以将所述应用服务节点的微服务信息和所述网关节点的微服务信息存储在所述服务注册和发现节点中。

4.根据权利要求1所述的方法，其特征在于，在所述调用网关节点中的路由信息监听服务之前，还包括：

调用所述网关节点中的安全访问服务，获取所述资源定位请求中的用户身份信息、IP地址和运行软件版本；

若所述用户身份信息中包含令牌信息，则确定所述资源定位请求的请求头包含令牌信息，对所述资源定位请求进行拦截；和/或

若在预定白名单中查询不存在所述IP地址，则对所述资源定位请求进行拦截；和/或

若所述运行软件版本的代码的注解标签中不包含预定代码，则确定所述网关节点处于生产环境，对所述资源定位请求进行拦截；其中，对于生产环境预定代码为prod。

5.根据权利要求1所述的方法，其特征在于，所述参数配置还包括预定频繁时间段和与所述预定频繁时间段对应的第一预定数量、预定休息时间段和与所述预定休息时间段对应的第二预定数量；

所述调用接口文档刷新服务，触发所述刷新事件，包括：

获取当前时间点，若所述当前时间点处于所述预定频繁时间段内、且累计的刷新事件数量大于或等于所述第一预定数量，则调用所述接口文档刷新服务，触发所述刷新事件；或

若所述当前时间点处于所述预定休息时间段内、且累计的刷新事件数量大于或等于所述第二预定数量，则调用所述接口文档刷新服务，触发所述刷新事件。

6.一种接口文档生成装置，其特征在于，包括：

信息聚合模块，用于接收用户点击地址生成的资源定位请求，在所述资源定位请求通过网关节点安全访问服务的情况下，调用网关节点中的路由信息监听服务，对服务注册和发现节点进行监听，得到刷新事件；其中，所述刷新事件为所述服务注册和发现节点在检测到所述网关节点拉取数据完毕后产生的；

调用接口文档刷新服务，触发所述刷新事件，读取所述服务注册和发现节点中的第一微服务列表数组、本地路由表数据库中的第二微服务列表数组和位于屏蔽名单中的第三微服务列表数组；其中，所述屏蔽名单位于参数配置中；

利用去重函数，对所述第一微服务列表数组、所述第二微服务列表数组和所述第三微服务列表数组进行去重操作，得到路由服务列表；其中，路由服务列表包括各个服务节点的路由信息；

信息获取模块，用于通过所述路由服务列表中的路由信息，进行代码文档信息获取；其中，所述代码文档信息包括接口文档链接；

文档生成模块，用于响应于对其中一个接口文档链接的点击操作，调用应用服务节点中的接口文档生成服务，获取与所述接口文档链接对应的接口文档并反馈。

7.一种电子设备，其特征在于，包括：

一个或多个处理器；

存储装置，用于存储一个或多个程序，

当所述一个或多个程序被所述一个或多个处理器执行，使得所述一个或多个处理器实现如权利要求1-5中任一所述的方法。

8.一种计算机可读介质，其上存储有计算机程序，其特征在于，所述程序被处理器执行时实现如权利要求1-5中任一所述的方法。

Images