CN112926290A - 生成展示接口文档的系统、方法及介质 - Google Patents

Abstract

本发明提供了一种生成展示接口文档的系统、方法及介质，包括：数据解析模块：将全量数据依据数据之间的联系进行解析拆分，同时过滤掉预设范围内的重复数据；数据展示模块：在界面编辑参数示例发送接口请求并展示相应数据；文档导出模块：生成所需项目的接口文档并导出，导出的接口文档内容格式根据需求进行设置编辑。本发明解决了当前不同项目接口文档不能统一观看、数据展示交互不友好、不可版本对比等问题，本发明可以浏览不同项目的接口文档、并且导出不同格式的文档，还能进行接口文档的历史版本对比、接口调用测试。

Description

生成展示接口文档的系统、方法及介质

技术领域

本发明涉及计算机应用技术领域，具体地，涉及一种生成展示接口文档的系统、方法及介质。

背景技术

当前技术条件下大多数接口文档一部分是通过方式一：服务端配置一些生成文档的插件，设置一些参数启动服务后会输出一个文档地址，一部分是通过方式二：服务器获取脚本对象符号形式的接口文档，对脚本对象符号形式的接口文档进行解析，并将解析得到的接口表，封装成表格实体，得到文字形式的接口文档。两种方式都有相同的一些问题，例如：具有局限性，展示数据不完整，展示效果不好，交互方式不友好，也无法拓展新的功能。方式一生成的文档地址还会收到相关环境的ip与端口影响，前端开发人员会需要依据不同项目、不同环境打开不同的页面查看接口文档，并且无法提供对外输出所需的文档。方式二问题在于生成的表格形式的接口数据，不够直观，也没有能够在线调用接口调试的功能，功能较为单一。

当前技术条件下接口文档通常都是展示最新版本的接口，查看不同版本的接口信息改动需要开发人员手动打开不同版本接口文档进行人工比对。

一般一些对外的接口文档需要开发人员手动编写，相应的介绍与目录。

专利文献CN110941950A(申请号：CN201911179920.3)公开了接口文档的生成方法、装置、服务器及存储介质。该系统存在以下弊端：(1)此发明对数据处理略显复杂，且转换流程较多较为复杂。(2)此发明没有良好的拓展性，难以进行更多功能的定制开发，后续维护性较低。(3)只能得到静态的接口信息，无法在线调用调试。(4)无法输出markdown形式接口文档。(5)数据展示不友好，不直观且不支持新旧版本文档对比与展示。

发明内容

针对现有技术中的缺陷，本发明的目的是提供一种生成展示接口文档的系统、方法及介质。

根据本发明提供的生成展示接口文档的系统，包括：

数据解析模块：将全量数据依据数据之间的联系进行解析拆分，同时过滤掉预设范围内的重复数据；

数据展示模块：在界面编辑参数示例发送接口请求并展示相应数据；

文档导出模块：生成所需项目的接口文档并导出，导出的接口文档内容格式根据需求进行设置编辑。

优选的，不同项目数据形式不同，对应的解析方式也不同，根据项目类型进行解析；

同时展示新旧版本的接口相关数据信息，并进行数据对比。

优选的，通过接口请求得到全量项目列表后，通过对应项目名称发送请求获取到该项目的全量数据，通过遍历数据获取项目名称、项目版本、项目简介、项目部署的ip与端口以及项目包含的全量接口数据，通过遍历接口的数据将全量的接口名称与路径匹配到对应模块。

优选的，设置项目和接口数据的格式，分别与项目主页和接口数据展示页面进行绑定，通过解析出的数据中的模块数据在页面中展示对应的菜单，通过所选菜单跳转对应主页，通过点击菜单栏子项接口名跳转到对应接口详情页。

根据本发明提供的生成展示接口文档的方法，包括：

数据解析步骤：将全量数据依据数据之间的联系进行解析拆分，同时过滤掉预设范围内的重复数据；

数据展示步骤：在界面编辑参数示例发送接口请求并展示相应数据；

文档导出步骤：生成所需项目的接口文档并导出，导出的接口文档内容格式根据需求进行设置编辑。

优选的，不同项目数据形式不同，对应的解析方式也不同，根据项目类型进行解析；

同时展示新旧版本的接口相关数据信息，并进行数据对比。

优选的，通过接口请求得到全量项目列表后，通过对应项目名称发送请求获取到该项目的全量数据，通过遍历数据获取项目名称、项目版本、项目简介、项目部署的ip与端口以及项目包含的全量接口数据，通过遍历接口的数据将全量的接口名称与路径匹配到对应模块。

优选的，设置项目和接口数据的格式，分别与项目主页和接口数据展示页面进行绑定，通过解析出的数据中的模块数据在页面中展示对应的菜单，通过所选菜单跳转对应主页，通过点击菜单栏子项接口名跳转到对应接口详情页。

根据本发明提供的一种存储有计算机程序的计算机可读存储介质，所述计算机程序被处理器执行时实现上述的方法的步骤。

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

(1)本发明解决了当前不同项目接口文档不能统一观看、数据展示交互不友好、不可版本对比等问题，本系统中可以浏览不同项目的接口文档、并且导出不同格式的文档，还能进行接口文档的历史版本对比、接口调用测试；

(2)本系统发明可同时读取不同版本的接口数据，解析数据后能比较数据的改动并且在页面进行标注高亮展示，方便开发人员直观感知版本更迭的接口改动点；

(3)本系统发明通过解析得到的数据根据所需文件类型以及内容形式，定制化相应处理算法处理后导出文件，大大提高文档编写的效率，降低开发成本。

附图说明

通过阅读参照以下附图对非限制性实施例所作的详细描述，本发明的其它特征、目的和优点将会变得更明显：

图1为本发明系统结构示意图。

具体实施方式

下面结合具体实施例对本发明进行详细说明。以下实施例将有助于本领域的技术人员进一步理解本发明，但不以任何形式限制本发明。应当指出的是，对本领域的普通技术人员来说，在不脱离本发明构思的前提下，还可以做出若干变化和改进。这些都属于本发明的保护范围。

实施例：

本发明是通过后端接口得到所有的项目接口数据，对这些数据进行拆解(即从这全量数据中提取出所需数据，并组成所需的格式对象)，将这些数据在页面中进行对应展示，并且可以修改参数示例调用接口。如图1，本系统包括如下模块：

数据解析模块：将全量复杂数据，依据其中联系解析拆分为后续模块直接使用的数据，同时过滤掉无用重复数据，不同项目数据形式可以不同，对应的解析方式也不同，可以根据项目类型进行定制化的解析。

通过接口请求得到全量项目列表后，通过对应项目名称发送请求获取到这个项目的全量数据，通过遍历数据获取项目名称、项目版本、项目简介、项目部署的ip与端口以及项目包含的全量接口数据。通过遍历接口的数据将全量的接口名称与路径匹配到对应的模块之下，项目模块数据包含模块名称、以及此模块下的接口列表，接口列表由接口名称与路径组成。将之前获取到的项目名称、项目版本、项目简介、项目ip与端口以及项目模块数据组成一个数据对象(记为A数据)。遍历接口数据匹配对应模块的同时，提取出接口的path(请求url)、接口名、请求方式、consumes(指定处理请求的提交内容类型)、响应数据处理内容类型、概述、具体描述、响应数据、请求数据，将这些数据组成一个数据对象(记为B数据)。B数据中的请求参数数据与响应数据要进行进一步的解析提取便于展示与使用，响应数据需要拆分为200、201、401、403、404(指代http状态码，表示网页服务器超文本传输协议响应状态的3位数字代码)等状态的数据对象(记为C数据)，C数据包含有状态码、说明、响应参数列表。请求数据需要拆分为请求参数列表、header(http协议请求头header)、body(http协议请求头body)等部分，header部分包含有请求的一些cookie、token等信息，body部分包含有post请求的请求参数列表。响应参数列表和请求参数列表是响应参数或请求参数的集合。请求参数和响应参数的参数组成数据类型相同，都是由参数类型、参数形式、参数描述、参数是否必选、参数是否允许为空、还有一些额外的参数说明，不同参数类型的参数说明不同，例如类型为number含有一些最大最小值的字段说明。上述指出的A、B、C三类数据则是需要解析得到的数据用于数据展示模块和markdown模块使用。

遍历数据指从按数据顺序从头至尾依次进行读取，当读取的数据为所需则放入新建的数据对象中，反之跳过继续读取。

数据展示模块：展示项目、接口相关数据信息，可以界面直接编辑请求参数示例发送接口请求并展示响应数据。可同时展示新旧版本的接口相关数据信息与对比。

通过配置前端路由：xx项目，这种格式与项目主页绑定。xx项目/xx模块/接口id，这种格式与接口数据展示页面绑定，通过解析出的A数据中的模块数据在页面中展示对应的菜单，通过所选菜单跳转对应主页，通过点击菜单栏子项接口名跳转到对应接口详情页。主页是展示对应项目的一些基础信息：项目标题、项目简介、项目版本、项目接口统计信息(不同类型的接口数量)、项目接口ip端口、项目接口basepath、导出markdown。接口详情页展示新老接口的接口数据(B数据)：接口标题、请求数据类型、响应数据类型、接口请求类型、接口描述、请求示例、请求参数表格、响应状态列表、响应参数表格、响应示例。响应状态表格展示不同状态码、对应的说明、对应的响应数据。请求示例与响应示例都是可编辑的区域，展示了请求参数或响应参数的数据示例值，可以修改参数示例的值发送请求会得到对应的接口返回数据。请求参数与响应参数都是表格展示，展示项为：参数名称、参数说明、数据类型。数据类型为object或array的数据可以折叠展示。详情页可以通过折叠按钮隐藏旧接口的数据展示，新版数据与旧版数据有不同的时候会通过高亮展示，更直观展示新版本的改动。数据展示页面使用的是tab菜单形式，所以可以缓存所查看的接口详情页，通过tab切换查看不同的项目不同模块的接口详情页更加的方便直观。

文档导出模块：生成所需项目的接口文档并导出，不同项目文档格式可以不相同，具有高拓展性。导出的接口文档内容格式可以进行所需的定制。

通过解析出来的A数据、B数据，可以将当前项目的全量数据信息转化为markdown文件导出。通过一系列处理逻辑将A数据、B数据转化为所需要的字符串，再通过window.URL.createObjectURL这个静态方法，通过字符串形式一行一行添入A数据与B数据，具体逻辑如下：遍历A数据，对A数据中标题字段生成字符串“#xx标题”添入，其它除模块数据的字段生成字符串“**xx字段**”添入，模块标题生成字符串“##xx标题”，其它除参数类的字段生成字符串“**xx字段**”添入，请求示例、相应示例、接口请求结果用字符串“```javascript xx数据```”这种形式添入，请求参数、响应参数用字符串"|参数名称|参数说明|类型|"这种形式添入。当参数数据类型为object或array这种内部还包含数据的对象，遍历过程中需根据层级添入“&emsp；&emsp；”(代表空格)，这样输出的文档请求参数、响应参数就会呈表格形式。

window.URL.createObjectURL静态方法会创建一个DOMString，其中包含一个表示参数中给出的对象的URL(一般指统一资源定位系统)。这个URL的生命周期和创建它的窗口中的document(每个载入浏览器的HTML文档都会成为Document对象，Document对象使我们可以从脚本中对HTML页面中的所有元素进行访问)绑定。这个新的URL对象表示指定的Blob对象(表示一个不可变、原始数据的类文件对象。它的数据可以按文本或二进制的格式进行读取，也可以转换成ReadableStream来用于数据操作)或File对象(是特殊类型的Blob，且可以用在任意的Blob类型的context中)。将组成的字符串作为参数，创建一个Blob对象，指出相应导出文件的编码类型，将Blob作为参数传入window.URL.createObjectURL方法得到对应的URL，将其作为a标签的href属性值，a标签的download属性值为导出文件名，触发a标签的click事件即完成了对应接口文档数据组成文件的下载。

本发明通过将数据在客户端进行处理，将所需展示的数据解析交给前端开发人员，展示的页面形式与数据格式都由前端人员把控，并且由于数据解析算法是由开发人员编写，可以实现多项目、多数据格式、多展现形式。本系统就是由于此种处理逻辑因此具有高拓展性，高复用性，通过部署次系统，各个项目都只需通过此系统查看接口文档，解决的生成接口文档的诸多不便，大大提高开发人员的工作效率，降低开发成本。

本领域技术人员知道，除了以纯计算机可读程序代码方式实现本发明提供的系统、装置及其各个模块以外，完全可以通过将方法步骤进行逻辑编程来使得本发明提供的系统、装置及其各个模块以逻辑门、开关、专用集成电路、可编程逻辑控制器以及嵌入式微控制器等的形式来实现相同程序。所以，本发明提供的系统、装置及其各个模块可以被认为是一种硬件部件，而对其内包括的用于实现各种程序的模块也可以视为硬件部件内的结构；也可以将用于实现各种功能的模块视为既可以是实现方法的软件程序又可以是硬件部件内的结构。

以上对本发明的具体实施例进行了描述。需要理解的是，本发明并不局限于上述特定实施方式，本领域技术人员可以在权利要求的范围内做出各种变化或修改，这并不影响本发明的实质内容。在不冲突的情况下，本申请的实施例和实施例中的特征可以任意相互组合。

Claims (9)

1.一种生成展示接口文档的系统，其特征在于，包括：

数据解析模块：将全量数据依据数据之间的联系进行解析拆分，并将拆分后的数据分别传输至数据展示模块和文档导出模块，同时过滤掉预设范围内的重复数据；

数据展示模块：在界面编辑参数示例发送接口请求并展示相应数据；

文档导出模块：生成所需项目的接口文档并导出，导出的接口文档内容格式根据需求进行设置编辑。

2.根据权利要求1所述的生成展示接口文档的系统，其特征在于，不同项目数据形式不同，对应的解析方式也不同，根据项目类型进行解析；

同时展示新旧版本的接口相关数据信息，并进行数据对比。

3.根据权利要求1所述的生成展示接口文档的系统，其特征在于，通过接口请求得到全量项目列表后，通过对应项目名称发送请求获取到该项目的全量数据，通过遍历数据获取项目名称、项目版本、项目简介、项目部署的ip与端口以及项目包含的全量接口数据，通过遍历接口的数据将全量的接口名称与路径匹配到对应模块。

4.根据权利要求1所述的生成展示接口文档的系统，其特征在于，设置项目和接口数据的格式，分别与项目主页和接口数据展示页面进行绑定，通过解析出的数据中的模块数据在页面中展示对应的菜单，通过所选菜单跳转对应主页，通过点击菜单栏子项接口名跳转到对应接口详情页。

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

数据解析步骤：将全量数据依据数据之间的联系进行解析拆分，同时过滤掉预设范围内的重复数据；

数据展示步骤：在界面编辑参数示例发送接口请求并展示相应数据；

文档导出步骤：生成所需项目的接口文档并导出，导出的接口文档内容格式根据需求进行设置编辑。

6.根据权利要求5所述的生成展示接口文档的方法，其特征在于，不同项目数据形式不同，对应的解析方式也不同，根据项目类型进行解析；

同时展示新旧版本的接口相关数据信息，并进行数据对比。

7.根据权利要求5所述的生成展示接口文档的方法，其特征在于，通过接口请求得到全量项目列表后，通过对应项目名称发送请求获取到该项目的全量数据，通过遍历数据获取项目名称、项目版本、项目简介、项目部署的ip与端口以及项目包含的全量接口数据，通过遍历接口的数据将全量的接口名称与路径匹配到对应模块。

8.根据权利要求5所述的生成展示接口文档的方法，其特征在于，设置项目和接口数据的格式，分别与项目主页和接口数据展示页面进行绑定，通过解析出的数据中的模块数据在页面中展示对应的菜单，通过所选菜单跳转对应主页，通过点击菜单栏子项接口名跳转到对应接口详情页。

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

Images