接口文档生成方法及系统与流程

1.本技术涉及数据处理技术领域，尤其涉及一种接口文档生成方法、系统、电子装置及计算机可读存储介质。


背景技术：

2.目前在生成接口文档时通常采用的是swagger。swagger是一个规范且完整的框架，用于生成、描述、调用和可视化restful风格的web服务。swagger的目标是对rest api定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过swagger进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，swagger消除了调用服务时可能会有的猜测。通俗的来讲，swagger就是将项目中所有(想要暴露的)接口展现在页面上，并且可以进行接口调用和测试的服务。
3.但是，swagger需要按照它的规范去定义接口及接口相关的信息，再通过衍生出来的一系列项目和工具，做到生成各种格式的接口文档。因为swagger等现有技术需要编写注解才能生成对应的接口文档，所以过程中需要人力介入，费时费力，且容易在编写时出错。
4.需要说明的是，上述内容并不用于限制申请保护范围。


技术实现要素：

5.本技术的主要目的在于提出一种接口文档生成方法、系统、电子装置及计算机可读存储介质，旨在解决如何自动快速生成接口文档的问题。
6.为实现上述目的，本技术实施例提供了一种接口文档生成方法，所述方法包括：
7.获取应用信息和应用下所有接口路径；
8.根据所述应用信息和所述接口路径读取对应接口的日志数据；
9.将所述日志数据按预设规则进行数据转换，得到接口文档数据；
10.将所述接口文档数据展示给用户。
11.可选地，所述获取应用信息和应用下所有接口路径后包括：
12.定时任务平台定时触发同步任务，更新服务树信息，得到最新应用信息；
13.通过所述应用信息中的应用编号在发布平台中获取对应服务容器的ip地址和端口信息；
14.根据所述ip地址和端口信息从bm接口中获取对应应用下所有接口路径。
15.可选地，所述根据所述应用信息和所述接口路径获取对应接口的日志数据包括：
16.根据所述应用信息和所述接口路径访问数据管理引擎，从所述数据管理引擎中得到对应接口的日志数据，并持久化存储于数据库中。
17.可选地，所述将所述日志数据按预设规则进行数据转换，得到接口文档数据包括：
18.获取全量日志数据；
19.对所述全量日志数据按照预设筛选条件进行筛选，并按照预设维度进行聚合；
20.将聚合后的数据按照预设数据格式进行格式转换，得到所述接口文档数据。
21.可选地，所述对所述全量日志数据按照预设筛选条件进行筛选，并按照预设维度进行聚合包括：
22.根据所述接口路径对所述全量日志数据进行第一轮筛选，得到第一筛选数据；
23.按照域名和所述接口路径对所述第一筛选数据进行聚合，得到第一聚合数据；
24.根据业务特例对所述第一聚合数据进行第二轮筛选，得到第二聚合数据。
25.可选地，所述将聚合后的数据按照预设数据格式进行格式转换包括：
26.从每一组所述聚合后的数据中选择一条数据；
27.将所选择的一条数据按照预设键值对转换为新的数据结构体，得到对应的接口文档数据。
28.可选地，所述方法在将所选择的一条数据按照预设键值对转换为新的数据结构体之前还包括：
29.对所选择的一条数据补充预设的特殊标识字段。
30.此外，为实现上述目的，本技术实施例还提供一种接口文档生成系统，所述系统包括：
31.获取模块，用于获取应用信息和应用下所有接口路径；
32.读取模块，用于根据所述应用信息和所述接口路径读取对应接口的日志数据；
33.转换模块，用于将所述日志数据按预设规则进行数据转换，得到接口文档数据；
34.展示模块，用于将所述接口文档数据展示给用户。
35.为实现上述目的，本技术实施例还提供一种电子装置，所述电子装置包括：存储器、处理器及存储在所述存储器上并可在所述处理器上运行的接口文档生成程序，所述接口文档生成程序被所述处理器执行时实现如上述的接口文档生成方法。
36.为实现上述目的，本技术实施例还提供一种计算机可读存储介质，所述计算机可读存储介质上存储有接口文档生成程序，所述接口文档生成程序被处理器执行时实现如上述的接口文档生成方法。
37.本技术实施例提出的接口文档生成方法、系统、电子装置及计算机可读存储介质，能够定时获取应用服务对应接口的日志数据，然后按照预设规则将所述日志数据自动转换为特定接口文档格式，并自动导入接口管理平台展示给用户查看，减少了人力介入的成本和差错性，并能持续的更新接口文档，保证稳定的时效性和可靠性。
附图说明
38.图1为实现本技术各个实施例的一种应用环境架构图；
39.图2为图1中服务端的一种功能组件结构示意图；
40.图3为本技术第一实施例提出的一种接口文档生成方法的流程示意图；
41.图4为图3中步骤s200的细化流程示意图；
42.图5为图3中步骤s204的细化流程示意图；
43.图6为所述第一实施例另一种形式的流程示意图；
44.图7为本技术第二实施例提出的一种电子装置的硬件架构示意图；
45.图8为本技术第三实施例提出的一种接口文档生成系统的模块示意图。
具体实施方式
46.为了使本技术的目的、技术方案及优点更加清楚明白，以下结合附图及实施例，对本技术进行进一步详细说明。应当理解，此处所描述的具体实施例仅用以解释本技术，并不用于限定本技术。基于本技术中的实施例，本领域普通技术人员在没有做出创造性劳动前提下所获得的所有其他实施例，都属于本技术保护的范围。
47.需要说明的是，在本技术实施例中涉及“第一”、“第二”等的描述仅用于描述目的，而不能理解为指示或暗示其相对重要性或者隐含指明所指示的技术特征的数量。由此，限定有“第一”、“第二”的特征可以明示或者隐含地包括至少一个该特征。另外，各个实施例之间的技术方案可以相互结合，但是必须是以本领域普通技术人员能够实现为基础，当技术方案的结合出现相互矛盾或无法实现时应当认为这种技术方案的结合不存在，也不在本技术要求的保护范围之内。
48.请参阅图1，图1为实现本技术各个实施例的一种应用环境架构图。本技术可应用于包括，但不仅限于客户端2、服务端4、网络6的应用环境中。
49.其中，所述客户端2用于向用户显示当前应用的界面和展示接口文档等。所述客户端2可以为pc(personal computer，个人电脑)、手机、平板电脑、便携计算机、可穿戴设备等终端设备。
50.所述服务端4用于为所述客户端2提供数据和技术支持。例如，所述服务端4根据应用信息和接口路径获取对应接口的日志数据，对日志数据进行数据转换后得到接口文档数据，再发送至所述客户端2中展示给用户。所述服务端4可以是机架式服务器、刀片式服务器、塔式服务器或机柜式服务器等计算设备，可以是独立的服务器，也可以是多个服务器所组成的服务器集群。
51.所述网络6可以是企业内部网(intranet)、互联网(internet)、全球移动通讯系统(global system of mobile communication，gsm)、宽带码分多址(wideband code division multiple access，wcdma)、4g网络、5g网络、蓝牙(bluetooth)、wi
‑
fi等无线或有线网络。所述服务端4和一个或多个所述客户端2之间通过所述网络6通信连接，以进行数据传输和交互。
52.另外，如图2所示，为所述服务端4的一种功能组件结构示意图。在图2中，定时任务平台用于定期触发任务，保证数据的有效性。服务树(tree)平台用于提供各个应用间的关联关系及其他信息。服务容器(container)为部署各个应用的容器。发布平台(caster)主要用于提供查询服务容器的各种信息。bm接口用于提供查询对应应用下所有接口信息的能力。权限校验功能用于控制各个组件平台的权限，保证系统的安全性。日志组件用于输出特定格式的应用日志到数据管理引擎(elasticsearch，简称es)。数据库中包括远程字典服务数据库(redis)和mongodb(一种基于分布式文件存储的数据库)。其中，redis提供队列功能，主要用于传递信息。mongodb提供持续化存储，用于数据查询。
53.bapi(business application programming interface，是面向对象程序设计方法中的一组程序接口)服务器用于从es中获取日志数据，持久化保存至数据库，并进行数据转换得到接口文档数据，然后发送至bapi客户端(客户端2)中展示给用户。
54.实施例一
55.如图3所示，为本技术第一实施例提出的一种接口文档生成方法的流程图。可以理
解，本方法实施例中的流程图不用于对执行步骤的顺序进行限定。根据需要，还可以对该流程图中的部分步骤进行添加或删减。下面以所述服务端4作为执行主体对该方法进行说明。
56.该方法包括以下步骤：
57.s200，获取应用信息和应用下所有接口路径。
58.具体而言，进一步参阅图4，为上述步骤s200的细化流程示意图。可以理解，该流程图不用于对执行步骤的顺序进行限定。根据需要，还可以对该流程图中的部分步骤进行添加或删减。在本实施例中，所述步骤s200具体包括：
59.s2000，定时任务平台定时触发同步任务，更新服务树信息，得到最新应用信息。
60.定时任务平台用于定期触发任务，保证数据的有效性。服务树平台用于提供各个应用间的关联关系及其他信息。当需要生成应用服务的接口文档时，定时任务平台定时(例如每天)触发同步任务，更新服务树平台中各个应用的信息，从而可以从所述服务树平台中获取得到最新的应用信息。所述应用信息中至少包括应用编号(id)。
61.可选地，此时还需要验证所述应用id的格式是否正确，若正确，则进入下一步骤，否则流程结束。
62.s2002，通过所述应用信息中的应用编号在发布平台获取服务容器的ip地址和端口(port)信息。
63.服务容器(container)为部署各个应用的容器。发布平台(caster)主要用于提供查询服务容器的各种信息。当获得应用id后，可以根据所述应用id从所述发布平台中获取得到对应的服务容器的ip地址和port信息。
64.s2004，根据所述ip地址和端口信息从bm接口中获取对应应用下所有接口路径。
65.bm接口提供查询对应应用下所有接口的能力。根据所获取的所述ip地址和port信息，即可从所述bm接口中查询得到对应应用下所有的接口路径。其中，首先根据所述ip地址和所述port信息获取对应的应用(app)服务节点，然后在所述app服务节点查询所述接口路径。
66.值得注意的是，在本实施例中，上述各个步骤中还包括权限校验功能，控制各个组件平台的权限，保证系统的安全性。具体的权限校验方式可以采用现有的可行方式，在此不再赘述。
67.回到图3，s202，根据所述应用信息和所述接口路径读取对应接口的日志数据。
68.日志组件可以输出特定格式的应用日志到es。在获取到所述应用信息和所述接口路径后，可以根据所述应用信息和所述接口路径访问es，从es中得到对应接口的日志数据。所述日志数据以json存储。
69.在得到所述日志数据后，解析所述日志数据并进行持久化存储，也就是写入数据库中。
70.s204，将所述日志数据按预设规则进行数据转换，得到接口文档数据。
71.具体而言，进一步参阅图5，为上述步骤s204的细化流程示意图。可以理解，该流程图不用于对执行步骤的顺序进行限定。根据需要，还可以对该流程图中的部分步骤进行添加或删减。在本实施例中，所述步骤s204具体包括：
72.s2040，获取全量日志数据。
73.上一步骤所读取的日志数据被解析并持久化存储于数据库中，可以从所述数据库
中获取全量日志数据。
74.s2042，对所述全量日志数据按照预设筛选条件进行筛选，并按照预设维度进行聚合。
75.举例而言，该步骤具体可以包括：
76.(1)根据所述接口路径对所述全量日志数据进行第一轮筛选，得到第一筛选数据。
77.(2)按照域名和所述接口路径对所述第一筛选数据进行聚合，得到第一聚合数据。也就是说，将相同域名和接口路径的第一筛选数据聚合到一个分组，每组数据的结构一样，对应的值可能不一样。
78.(3)根据业务特例对所述第一聚合数据进行第二轮筛选，得到第二聚合数据。
79.由于某些特殊的业务场景(业务特例)的数据格式可能不支持这种数据转换，因此在进行第一轮筛选和聚合之后，还要通过第二轮筛选将这些业务特例对应的数据进行剔除。
80.在其他实施例中，所述预设筛选条件和所述预设维度都可以根据具体应用场景进行自定义设置，在此不再赘述。
81.s2044，将聚合后的数据按照预设数据格式进行格式转换，得到所述接口文档数据。
82.经过上一步骤的聚合后，相同域名和接口路径的数据会被聚合为一组，从每一组所述聚合后的数据(第二聚合数据)中选择一条数据，将所选择的一条数据按照预设键值对转换为新的数据结构体，可以得到对应的接口文档数据。
83.所述选择一条数据可以将聚合得到的数据通过得到的返回结果的状态码进行挑选，确保取到一条返回结果为正确的数据。具体而言，在上述步骤s2040中获取全量日志数据时，请求数据后返回的每一条数据都会有一个状态码，以表示该条数据的状态是否正常。例如，假设因为网络不佳等原因对某一条数据获取失败，该条数据的返回结果的状态码即为错误。因此，在从每一组所述聚合后的数据(第二聚合数据)中选择一条数据时，需要根据返回结果中的状态码进行挑选，即从状态码为正确的数据中任选一条即可。
84.优选地，还需要对所选择的一条数据补充一些预设的特殊标识字段，然后再组成新的键值对的数据结构体，得到对应的接口文档数据。所述特殊标识字段一般是指该条数据中没有，但导入bapi的所述接口文档数据中时必须要有的字段，例如对环境、配置的一些设置字段等，可以为空值。
85.回到图3，s206，将所述接口文档数据展示给用户。
86.在经过数据转换得到所述接口文档数据后，将所述接口文档数据发送至客户端(导入bapi)，在客户端中可以将所述接口文档数据展示给用户。
87.本实施例提出的接口文档生成方法，可以定时通过服务树平台、bm框架和es系统获取对应接口的日志数据，然后按照预设规则将所述日志数据自动转换为特定接口文档格式，并自动导入接口管理平台(bapi)展示给用户查看，减少了人力介入的成本和差错性，并能持续的更新接口文档，保证稳定的时效性和可靠性。
88.如图6所示，为所述第一实施例另一种形式的流程示意图。在图6中，通过更新服务树平台(tree)的信息得到最新的应用信息(应用id)，并验证所述应用id的格式是否正确，若正确则执行下一步骤，否则流程结束。在发布平台(caster)通过所述应用id获取服务容
器的ip地址和port信息。根据所述ip地址和所述port信息获取对应的app服务节点，然后在所述app服务节点查询所述接口路径。bapi服务端(bapi
‑
server)根据所述应用信息和所述接口路径从es中读取对应接口的日志数据，然后解析所述日志数据并进行持久化存储，也就是写入数据库中。再将所述日志数据按预设规则进行数据转换，得到接口文档数据。最后将所述接口文档数据发送至bapi客户端(bapi
‑
client)，导入bapi，展示给用户查看。
89.通过服务树平台、发布平台、bm框架、es、bapi服务端、bapi客户端之间的配合，可以自动获取应用服务对应接口的日志数据，然后将所述日志数据自动转换为特定接口文档格式，并自动导入接口管理平台(bapi)展示给用户查看，减少了人力介入的成本和差错性，并能持续的更新接口文档，保证稳定的时效性和可靠性。
90.实施例二
91.如图7所示，为本技术第二实施例提出一种电子装置20的硬件架构示意图。本实施例中，所述电子装置20可包括，但不仅限于，可通过系统总线相互通信连接的存储器21、处理器22、网络接口23。需要指出的是，图7仅示出了具有组件21
‑
23的电子装置20，但是应理解的是，并不要求实施所有示出的组件，可以替代的实施更多或者更少的组件。在本实施例中，所述电子装置20可以是所述服务端4。
92.所述存储器21至少包括一种类型的可读存储介质，所述可读存储介质包括闪存、硬盘、多媒体卡、卡型存储器(例如，sd或dx存储器等)、随机访问存储器(ram)、静态随机访问存储器(sram)、只读存储器(rom)、电可擦除可编程只读存储器(eeprom)、可编程只读存储器(prom)、磁性存储器、磁盘、光盘等。在一些实施例中，所述存储器21可以是所述电子装置20的内部存储单元，例如该电子装置20的硬盘或内存。在另一些实施例中，所述存储器21也可以是所述电子装置20的外部存储设备，例如该电子装置20上配备的插接式硬盘，智能存储卡(smart media card,smc)，安全数字(secure digital,sd)卡，闪存卡(flash card)等。当然，所述存储器21还可以既包括所述电子装置20的内部存储单元也包括其外部存储设备。本实施例中，所述存储器21通常用于存储安装于所述电子装置20的操作系统和各类应用软件，例如接口文档生成系统60的程序代码等。此外，所述存储器21还可以用于暂时地存储已经输出或者将要输出的各类数据。
93.所述处理器22在一些实施例中可以是中央处理器(central processing unit，cpu)、控制器、微控制器、微处理器、或其他数据处理芯片。该处理器22通常用于控制所述电子装置20的总体操作。本实施例中，所述处理器22用于运行所述存储器21中存储的程序代码或者处理数据，例如运行所述接口文档生成系统60等。
94.所述网络接口23可包括无线网络接口或有线网络接口，该网络接口23通常用于在所述电子装置20与其他电子设备之间建立通信连接。
95.实施例三
96.如图8所示，为本技术第三实施例提出一种接口文档生成系统60的模块示意图。所述接口文档生成系统60可以被分割成一个或多个程序模块，一个或者多个程序模块被存储于存储介质中，并由一个或多个处理器所执行，以完成本技术实施例。本技术实施例所称的程序模块是指能够完成特定功能的一系列计算机程序指令段，以下描述将具体介绍本实施例各程序模块的功能。
97.在本实施例中，所述接口文档生成系统60包括：
98.获取模块600，用于获取应用信息和应用下所有接口路径。
99.具体而言，所述获取模块600获取所述应用信息和接口路径的过程包括：
100.(1)定时任务平台定时触发同步任务，更新服务树信息，得到最新应用信息。
101.定时任务平台用于定期触发任务，保证数据的有效性。服务树平台用于提供各个应用间的关联关系及其他信息。当需要生成应用服务的接口文档时，定时任务平台定时(例如每天)触发同步任务，更新服务树平台中各个应用的信息，从而可以从所述服务树平台中获取得到最新的应用信息。所述应用信息中至少包括应用id。
102.(2)通过所述应用信息中的应用id在发布平台获取服务容器的ip地址和port信息。
103.服务容器(container)为部署各个应用的容器。发布平台(caster)主要用于提供查询服务容器的各种信息。当获得应用id后，可以根据所述应用id从所述发布平台中获取得到对应的服务容器的ip地址和port信息。
104.(3)根据所述ip地址和port信息从bm接口中获取对应应用下所有接口路径。
105.bm接口提供查询对应应用下所有接口的能力。根据所获取的所述ip地址和port信息，即可从所述bm接口中查询得到对应应用下所有的接口路径。其中，首先根据所述ip地址和所述port信息获取对应的应用(app)服务节点，然后在所述app服务节点查询所述接口路径。
106.值得注意的是，在本实施例中，上述过程中还包括权限校验功能，控制各个组件平台的权限，保证系统的安全性。具体的权限校验方式可以采用现有的可行方式，在此不再赘述。
107.读取模块602，用于根据所述应用信息和所述接口路径读取对应接口的日志数据。
108.日志组件可以输出特定格式的应用日志到es。在获取到所述应用信息和所述接口路径后，可以根据所述应用信息和所述接口路径访问es，从es中得到对应接口的日志数据。所述日志数据以json存储。
109.在得到所述日志数据后，解析所述日志数据并进行持久化存储，也就是写入数据库中。
110.转换模块604，用于将所述日志数据按预设规则进行数据转换，得到接口文档数据。
111.具体而言，所述转换模块604进行数据转换的过程包括：
112.(1)获取全量日志数据。
113.读取模块602所读取的日志数据被解析并持久化存储于数据库中，可以从所述数据库中获取全量日志数据。
114.(2)对所述全量日志数据按照预设筛选条件进行筛选，并按照预设维度进行聚合。
115.举例而言，该过程具体可以包括：
116.根据所述接口路径对所述全量日志数据进行第一轮筛选，得到第一筛选数据；
117.按照域名和所述接口路径对所述第一筛选数据进行聚合，得到第一聚合数据；
118.根据业务特例对所述第一聚合数据进行第二轮筛选，得到第二聚合数据。
119.在其他实施例中，所述预设筛选条件和所述预设维度都可以根据具体应用场景进行自定义设置，在此不再赘述。
120.(3)将聚合后的数据按照预设数据格式进行格式转换，得到所述接口文档数据。
121.经过上述聚合后，相同域名和接口路径的数据会被聚合为一组，从每一组所述聚合后的数据(第二聚合数据)中选择一条数据，将所选择的一条数据按照预设键值对转换为新的数据结构体，可以得到对应的接口文档数据。
122.所述选择一条数据可以将聚合得到的数据通过得到的返回结果的状态码进行挑选，确保取到一条返回结果为正确的数据。具体而言，在上述获取全量日志数据时，请求数据后返回的每一条数据都会有一个状态码，以表示该条数据的状态是否正常。例如，假设因为网络不佳等原因对某一条数据获取失败，该条数据的返回结果的状态码即为错误。因此，在从每一组所述聚合后的数据(第二聚合数据)中选择一条数据时，需要根据返回结果中的状态码进行挑选，即从状态码为正确的数据中任选一条即可。
123.优选地，还需要对所选择的一条数据补充一些预设的特殊标识字段，然后再组成新的键值对的数据结构体，得到对应的接口文档数据。所述特殊标识字段一般是指该条数据中没有，但导入bapi的所述接口文档数据中时必须要有的字段，例如对环境、配置的一些设置字段等，可以为空值。
124.展示模块606，用于将所述接口文档数据展示给用户。
125.在经过数据转换得到所述接口文档数据后，将所述接口文档数据发送至客户端(导入bapi)，在客户端中可以将所述接口文档数据展示给用户。
126.本实施例提出的接口文档生成系统，可以定时通过服务树平台、bm框架和es系统获取对应接口的日志数据，然后按照预设规则将所述日志数据自动转换为特定接口文档格式，并自动导入接口管理平台(bapi)展示给用户查看，减少了人力介入的成本和差错性，并能持续的更新接口文档，保证稳定的时效性和可靠性。
127.实施例四
128.本技术还提供了另一种实施方式，即提供一种计算机可读存储介质，所述计算机可读存储介质存储有接口文档生成程序，所述接口文档生成程序可被至少一个处理器执行，以使所述至少一个处理器执行如上述的接口文档生成方法的步骤。
129.需要说明的是，在本文中，术语“包括”、“包含”或者其任何其他变体意在涵盖非排他性的包含，从而使得包括一系列要素的过程、方法、物品或者装置不仅包括那些要素，而且还包括没有明确列出的其他要素，或者是还包括为这种过程、方法、物品或者装置所固有的要素。在没有更多限制的情况下，由语句“包括一个
……”
限定的要素，并不排除在包括该要素的过程、方法、物品或者装置中还存在另外的相同要素。
130.上述本技术实施例序号仅仅为了描述，不代表实施例的优劣。
131.显然，本领域的技术人员应该明白，上述的本技术实施例的各模块或各步骤可以用通用的计算装置来实现，它们可以集中在单个的计算装置上，或者分布在多个计算装置所组成的网络上，可选地，它们可以用计算装置可执行的程序代码来实现，从而，可以将它们存储在存储装置中由计算装置来执行，并且在某些情况下，可以以不同于此处的顺序执行所示出或描述的步骤，或者将它们分别制作成各个集成电路模块，或者将它们中的多个模块或步骤制作成单个集成电路模块来实现。这样，本技术实施例不限制于任何特定的硬件和软件结合。
132.以上仅为本技术实施例的优选实施例，并非因此限制本技术实施例的专利范围，
凡是利用本技术实施例说明书及附图内容所作的等效结构或等效流程变换，或直接或间接运用在其他相关的技术领域，均同理包括在本技术实施例的专利保护范围内。