接口文档生成方法、系统和计算机可读存储介质与流程

1.本发明涉及计算机技术领域，特别涉及一种接口文档生成方法、系统和计算机可读存储介质。


背景技术：

2.在接口开发过程中，开发人员需要提供完善的接口文档。接口文档的手工编写浪费了开发人员的开发时间，效率低且容易出错。而现有的自动化生成工具有些也需要手工编写配置文件，效率提升不够明显；另外，有些自动化生成工具需要引入额外的注解来标记接口，这种做法会对原有系统造成一定的侵入性。


技术实现要素：

3.本发明旨在至少解决现有技术中存在的技术问题之一，提出了一种接口文档生成方法、接口文档生成系统和计算机可读存储介质。
4.第一方面，本公开实施例提供了一种接口文档生成方法，包括：
5.从接口代码中提取接口的原始参数信息，所述原始参数信息包括多个原始参数；
6.根据预先设置的映射模版对各所述原始参数进行参数解析，得到各所述原始参数的解释信息，所述映射模版包括不同字段及其对应的解释信息；
7.根据各所述原始参数的所述解释信息生成接口文档。
8.在一些实施例中，所述多个原始参数包括：请求参数和响应参数。
9.在一些实施例中，所述请求参数的数量为多个，所述响应参数的数量为多个；
10.在从接口代码中提取接口的原始参数信息的步骤之后且在根据预先设置的映射模版对各所述原始参数进行参数解析的步骤之前，还包括：
11.对多个所述请求参数进行数据层级树形结构的构建以得到请求参数之间的层级关系，以及对多个所述响应参数进行数据层级树形结构的构建以得到响应参数之间的层级关系；
12.所述接口文档内记载有所述请求参数之间的层级关系以及所述响应参数之间的层级关系。
13.在一些实施例中，对多个所述请求参数进行数据层级树形结构的构建的步骤包括：
14.利用临时表存储扁平化的多个所述请求参数，并利用递归法将扁平化的多个所述请求参数转换为树形结构；
15.对多个所述响应参数进行数据层级树形结构的构建的步骤包括：
16.利用临时表存储扁平化的多个所述响应参数，并利用递归法将扁平化的多个所述响应参数转换为树形结构。
17.在一些实施例中，在利用递归法将扁平化的多个所述请求参数或扁平化的多个所述响应参数转换为树形结构的过程中，若识别出当前待处理的所述请求参数或响应参数的
为泛型集合类参数且存在所述泛型集合类参数的测试数据时，则根据所述测试数据确定所述泛型集合类参数所对应节点的子节点。
18.在一些实施例中，所述多个原始参数包括：接口地址。
19.根据预先设置的映射模版对接口地址进行参数解析的步骤包括：
20.根据所述接口地址中的分隔符对所述接口地址进行分割，得到多个字符串；
21.使用所述映射模版对各所述字符串进行参数解析，得到各所述字符串的解释信息；
22.基于各所述字符串的解释信息得到所述接口地址的解释信息。
23.在一些实施例中，所述接口文档生成方法还包括：
24.从测试缓存中获取请求示例和/或响应示例；
25.将所述请求示例和/或所述响应示例记载于所述接口文档内。
26.在一些实施例中，所述多个原始参数包括：接口类型。
27.在一些实施例中，在根据各所述原始参数的所述解释信息生成接口文档的步骤之后，还包括：
28.响应于修改指令对所述接口文档进行相应修改。
29.第二方面，本公开实施例还提供了一种用于实现如第一方面中提供的所述方法的接口文档生成系统，包括：
30.提取模块，配置为从接口代码中提取接口的原始参数信息，所述原始参数信息包括多个原始参数；
31.解析模块，配置为根据预先设置的映射模版对各所述原始参数进行参数解析，得到各所述原始参数的解释信息，所述映射模版包括不同字段及其对应的解释信息；
32.生成模块，配置为根据各所述原始参数的所述解释信息生成接口文档。
33.第三方面，本公开实施例还提供了一种计算机可读存储介质，所述计算机可读存储介质中存储有计算机执行指令，当处理器执行所述计算机执行指令时，实现上述第一方面中提供的所述方法。
附图说明
34.图1为本公开实施例提供的一种接口文档生成方法的流程图；
35.图2为本公开实施例提供的另一种接口文档生成方法的流程图；
36.图3为本公开实施例提供的再一种接口文档生成方法的流程图；
37.图4为本公开实施例中对请求参数进行数据层级树形结构构建的一种示意图；
38.图5为本公开实施例中对响应参数进行数据层级树形结构构建的一种示意图；
39.图6为本公开实施例中生成接口文档的一种示意图；
40.图7为本公开实施例提供的再一种接口文档生成方法的流程图；
41.图8为本公开实施例所提供的一种接口文档生成系统的结构框图。
具体实施方式
42.为使本领域的技术人员更好地理解本发明的技术方案，下面结合附图对本发明提供的一种接口文档生成方法、接口文档生成系统和计算机可读存储介质进行详细描述。
43.图1为本公开实施例提供的一种接口文档生成方法的流程图，如图1所示，该接口文档生成方法包括：
44.步骤s1、从接口代码中提取接口的原始参数信息。
45.在开发人员完成应用程序接口(application programming interface，简称api)的接口代码后，可基于接口代码提取出接口的原始参数信息，该原始参数信息包括多个原始参数。
46.在本公开实施例中，接口的原始参数信息是指在接口代码中用于描述接口属性的信息；例如，接口地址、接口类型、请求参数、响应参数。
47.其中，接口地址的本质为一个统一资源定位器(uniform resource locator，简称url)，用来唯一的标识一个资源，需求方可通过调用接口url获取相应内容；接口类型(也称为请求方式)一般包括如下四种情况：post(新增)、put(修改)、delete(删除)和get(获取)；请求参数是指需要向接口请求的参数(本质为字段)；响应参数是指接口返回的参数(本质为字段)。
48.在实际应用中，可根据实际需要(例如，接口文档所需要记载的内容)来提取出所需要的原始参数信息。具体地，可通过一些现有的参数提取工具来进行原始参数信息的提取，或者是通过自定义提取算法来进行原始参数信息的提取。
49.步骤s2、根据预先设置的映射模版对各原始参数进行参数解析，得到各原始参数的解释信息。
50.其中，映射模版可进行预先设计和存储，映射模版包括不同字段及其对应的解释信息；解释信息可用于描述对应字段所代表的含义。例如，解释信息可用于中文描述该字段的含义。在步骤s2中，基于该预先设置的映射模版可获取到各原始参数的解释信息，得到的解释信息可用于描述原始参数所代表的含义。
51.以映射模版为映射对应关系表的情况为例，下面表1示例性给出了一个映射对应关系表内记载有不同字段以及各字段对应的解释信息的情况。
52.字段解释信息user用户pagelist分页查询add新增update更新delete删除query查询
53.表1.不同字段以及各字段对应的解释信息的映射对应关系表
54.步骤s3、根据各原始参数的解释信息生成接口文档。
55.在步骤s3中，可基于步骤s2得到的解析结果来生成相应的接口文档，接口文档中至少包括有各原始参数及其对应的解释信息。
56.基于上述内容可见，本公开的技术方案通过提取接口的原始参数，并根据映射模版来对各原始参数进行参数解析，且根据各原始参数的解释信息自动生成接口文档，从而实现在接口代码没有注解信息的情况下自动生成接口文档，可以极大减少人工干预成本，避免了生成接口文档时需要强依赖于注解信息的现象。
57.图2为本公开实施例提供的另一种接口文档生成方法的流程图，如图2所示，在一些实施例中通过步骤s1所提取出的接口的原始参数信息包括多个请求参数和多个响应参数，此时在步骤s1和步骤s2之间还包括步骤s1a。
58.步骤s1a、对多个请求参数进行数据层级树形结构的构建以得到请求参数之间的层级关系，以及对多个响应参数进行数据层级树形结构的构建以得到响应参数之间的层级关系。
59.此时，在步骤s3中还可将请求参数之间的层级关系和响应参数之间的层级关系记载于接口文档内。
60.在实际应用中，会出现请求参数或响应参数为泛型集合类参数的情况，此时响应参数之间或响应参数之间会存在层级关系；在通过步骤s1完成原始参数信息的提取之后，通过步骤s1a来还原请求参数之间的层级关系以及响应参数之间的层级关系，且将该层级关系记载于接口文档内，可使得开发人员基于接口文档能够对泛型集合类参数进行准确的还原。本公开实施例提供的技术方案可适配于具有泛型集合类参数的接口。
61.在一些实施例中，在步骤s1a内对多个请求参数进行数据层级树形结构的构建的步骤包括：利用临时表存储扁平化的多个请求参数，并利用递归法将扁平化的多个请求参数转换为树形结构；在步骤s1a内对多个响应参数进行数据层级树形结构的构建的步骤包括：利用临时表存储扁平化的多个响应参数，并利用递归法将扁平化的多个响应参数转换为树形结构。通过上述方式，可实现对参数类型为泛型集合类的请求参数或响应参数的层级结构构建。需要说明的是，利用递归法将扁平化数据转换为树形结构的具体过程属于本领域的常规知识，此处不进行详细描述。
62.在一些实施例中，在利用递归法将扁平化的多个请求参数或扁平化的多个响应参数转换为树形结构的过程中，若识别出当前待处理的请求参数或响应参数的为泛型集合类参数且存在泛型集合类参数的测试数据时，则根据测试数据确定泛型集合类参数所对应节点的子节点。
63.一般地，在完成接口代码的编写后会进行接口测试，接口测试过程中所使用到的请求参数和响应参数都会被记录、缓存。也就是说，在接口测试过程中，若对泛型集合类参数进行了测试，则该泛型集合类参数所包含的所有参数以及参数的层级关系都会被记录，此时基于测试数据可得到该泛型集合类参数的数据结构，即得到在树形结构中以泛型集合类参数作为父节点的所有子节点以及这些子节点之间的层级关系。在本公开实施例中，基于测试数据来确定泛型集合类参数所对应节点的子节点的方式，可有效减少递归处理过程中的数据处理量。
64.在一些实施例中，在步骤s2中根据根据预先设置的映射模版对请求参数/响应参数进行参数解析的步骤包括：针对每一个请求参数/响应参数，从映射模版中查询出请求参数/响应参数的字段所对应的解释信息。
65.在一些实施例中，在接口文档内可以以列表的形式呈现各请求参数、各请求参数对应的解释信息以及请求参数之间的层级关系；在接口文档内可以以列表的形式呈现各响应参数、各响应参数对应的解释信息以及响应参数之间的层级关系。
66.在一些实施例中，通过步骤s1所提取出的接口的原始参数信息包括：接口地址。在步骤s2中根据根据预先设置的映射模版对接口地址进行参数解析的步骤包括：根据接口地
址中的分隔符(接口地址中的分隔符一般为斜杠“/”)对接口地址进行分割，得到多个字符串；使用映射模版对各字符串进行参数解析，得到各字符串的解释信息；基于各字符串的解释信息得到接口地址的解释信息。
67.作为一个示例接口地址为：/user/add，该接口地址先被分割为“user”和“add”两个字符串，然后基于表1所示映射模版可得到“user”对应的解释信息为“新增”，“add”对应的解释信息为“用户”，最后得到接口地址为：/user/add所对应的解释信息为“新增用户”。
68.同理，接口地址为：/user/query所对应的解释信息为“查询用户”，接口地址为：/user/pagelist所对应的解释信息为“分页查询用户”，接口地址为：/user/update所对应的解释信息为“更新用户”，接口地址为：/user/delete所对应的解释信息为“删除用户”。
69.在一些实施例中，通过步骤s1所提取出的接口的原始参数信息包括：接口类型。
70.图3为本公开实施例提供的再一种接口文档生成方法的流程图，如图3所示，该接口文档生成方法不但包括前述实施例中的步骤s1～步骤s3，且还包括步骤s1b和步骤s3a。
71.步骤s1b、从测试缓存中获取请求示例和/或响应示例。
72.步骤s3a、将请求示例和/或响应示例记载于接口文档内。
73.在完成接口测试后，测试数据中包含有请求示例和响应示例，可将测试数据中的请求示例和响应示例记载于接口文档内以作为接口示例，无需额外编写接口示例。
74.在一些实施例中，步骤s1b可以与步骤s1或步骤s1a同步执行，步骤s3a可以与步骤s3同步执行。当然，在本公开实施例中仅需保证步骤s1b位于步骤s3a之前执行即可。
75.为便于本领域技术人员更清楚的理解本公开的技术方案，下面将结合一个示例对本公开所提供的接口文档生成方法进行详细描述。
76.若通过步骤s1从接口代码中提取接口的原始参数信息如下：
77.接口地址为：地址1；
78.接口类型为：类型1；
79.请求参数为：
80.参数a(参数a1，参数a2，参数a3,参数a4)
81.参数a3(参数a3_1，参数a3_2，参数a3_3)
82.参数a3_2(参数a3_2_1,参数a3_2_2)
83.参数a4(参数a4_1，参数a4_2)
84.参数b(参数b1，参数b2)；
85.参数c；
86.响应参数为：
87.参数d(参数d1，参数d2，参数d3)
88.参数d2(参数d2_1，参数d2_2)
89.参数d2_1(参数d2_1_1，参数d2_1_1)
90.参数e；
91.其中，上述参数a、参数b和参数d均为泛型集合类参数；具体地，参数a包括参数a1、参数a2、参数a3和参数a4，参数a3为泛型集合类参数，参数a3包括参数a3_1、参数a3_2和参数a3_3，参数a3_2为泛型集合类参数，参数a3_2包括参数a3_2_1和参数a3_2_2，参数a4为泛型集合类参数，参数a4包括参数a4_1和参数a4_2；参数b包括参数b1和参数b2；参数d包括参
数d1、参数d2和参数d3，参数d2为泛型集合类参数，参数d2包括参数d2_1和参数d2_2，参数d2_1为泛型集合类参数，参数d2_1包括参数d2_1_1和参数d2_1_1。
92.参数c、参数e、参数a1、参数a2、参数a3_1、参数a3_2_1、参数a3_2_2、参数a3_3、参数a4_1、参数a4_2、参数b1、参数b2、参数d1、参数d3的参数类型分别独立选自常规数据类型，例如string类型、long类型、integer类型等。
93.需要说明的是，通过步骤s1所获取到的请求参数和响应参数均为扁平化数据。
94.图4为本公开实施例中对请求参数进行数据层级树形结构构建的一种示意图，如图4所示，通过步骤1a对多个请求参数进行数据层级树形结构的构建，可以得到请求参数所对应的树形结构，该树形结构的层数为五层，各层所对应的请求参数可参见图4所示。此时，由请求参数构建的树形结构可以表示为：(参数a(参数a1，参数a2，参数a3(参数a3_1，参数a3_2(参数a3_2_1,参数a3_2_2)，参数a3_3)，参数a4(参数a4_1，参数a4_2))，参数b(参数b1，参数b2)，参数c)。
95.图5为本公开实施例中对响应参数进行数据层级树形结构构建的一种示意图，图5所示，通过步骤1a对多个响应参数进行数据层级树形结构的构建，可以得到响应参数所对应的树形结构，该树形结构的层数为五层，各层所对应的响应参数可参见图5所示。此时，由响应参数构建的树形结构可以表示为：(参数d(参数d1，参数d2(参数d2_1(参数d2_1_1，参数d2_1_1)，参数d2_2)，参数d3)，参数e)。
96.通过上述步骤1a可以对接口代码内泛型集合类参数进行精准的还原，使得本公开的技术方案能够适用于具有泛型集合类参数的接口的场景。当然，本领域技术人员应该知晓的是，在步骤s1和步骤s2之间执行上述步骤1a为本公开中的一种可选实施方案，在一些实施例中也可以不执行该步骤1a。
97.接着，可利用预先配置映射模版来对各原始参数进行参数解析，得到各原始参数的解释信息。需要说明的是，在进行参数解析时，对于集合类参数也会对该集合类参数所包含的各参数进行参数解析。在实际应用中，在对不同接口的接口代码进行处理以生成对应接口文档时，所采用的映射模版可以采用相同映射模版，也可以采用不同的映射模版，可进行具体情况来配置合适的映射模版。
98.此外，还可以从测试缓存中获取到请求示例和/或响应示例。
99.图6为本公开实施例中生成接口文档的一种示意图，如图6所示，在步骤s3中，根据接口地址、接口类型、请求参数、响应参数及其对应解释信息、请求示例、响应示例来生成接口文档。其中，该接口文档内记载有接口地址及其对应的解释信息、接口类型及其对应的解释信息、各请求参数及其对应的解释信息(接口文档内的内容也可以反应出各请求桉树之间的层级关系)，各响应参数及其对应的解释信息(接口文档内的内容也可以反应出各响应参数之间的层级关系)、请求示例和响应示例。
100.图6中仅示例性给出了利用树状层级结构表来展示请求参数和响应参数的情况，该情况仅起到示例性作用。树状层级结构表可以直观的体现出请求参数之间的层级关系以及响应参数之间的层级关系。
101.当然，在步骤s1进行原始参数信息的提取时，不仅可以提取出各请求参数和各响应参数所对应的字段，还可以提取出对应的参数类型，在生成接口文档的过程中，可以将各请求参数和各响应参数的参数类型记载于接口文档内。
102.图7为本公开实施例提供的再一种接口文档生成方法的流程图，如图7所示，该接口文档生成方法不但包括前述实施例中的步骤s1～步骤s3，且在步骤s3之后还包括：步骤s4。
103.步骤s4、响应于修改指令对接口文档进行相应修改。
104.在系统根据各原始参数的解释信息生成接口文档之后，用户可对生成的接口文档进行修改，系统响应于修改指令对接口文档进行相应修改。当然，用户还可以通过操作对最终的接口文档进行确认。
105.需要说明的是，上述各实施例中不同的步骤之间可以相互进行组合，通过组合后所得到的技术方案也应属于本公开的保护范围。例如，在一些实施例中，接口文档的生成方法同时包括步骤s1、步骤s1a、步骤s1b、步骤s2、步骤s3和步骤s3a，对于其他组合方案此处不再一一举例描述。
106.基于同一发明构思，本公开实施例还提供了一种接口文档生成系统，该接口文档生成系统可用于实现前面实施例提供的接口文档生成方法。图8为本公开实施例所提供的一种接口文档生成系统的结构框图，如图8所示，该接口文档生成系统包括：提取模块1、解析模块2和生成模块3。
107.其中，提取模块1配置为从接口代码中提取接口的原始参数信息，原始参数信息包括多个原始参数；解析模块2配置为根据预先设置的映射模版对各原始参数进行参数解析，得到各原始参数的解释信息，映射模版包括不同字段及其对应的解释信息；生成模块3配置为根据各原始参数的解释信息生成接口文档。
108.对于各模块的具体工作过程可参见前面实施例中对相应步骤的具体描述，此处不再赘述。
109.需要说明的是，本公开实施例中的提取模块1具体可用于实现前面实施例中的步骤s1、步骤s1a和步骤s1b；本公开实施例中的解析模块2具体可用于实现前面实施例中的步骤s2；本公开实施例中生成模块3具体可用户实现前面实施例中的步骤s3和步骤s3a。
110.在一些实施例中，该接口文档生成系统还可以包括修改模块4，修改模块4配置为响应于修改指令对接口文档进行相应修改。修改模块4具体可用于实现前面实施例中的步骤s4。
111.作为一种应用场景，提取模块1可以以“应用插件”的形式设置在客户端，解析模块2、生成模块3可以设置在管理端(例如，服务云端)，由管理端来实现参数解析和生成接口文档的功能；当然，解析模块2和生成模块3也可以设置在客户端；这些情况，均应属于本公开的保护范围。
112.基于同一发明构思，本公开实施例还提供一种计算机可读存储介质，该计算机可读存储介质中存储有计算机执行指令，当处理器执行所述计算机执行指令时，实现上述任一实施例中的接口文档生成方法的技术方案，其实现原理以及有益效果与接口文档生成方法的实现原理及有益效果类似，可参见接口文档生成方法的实现原理及有益效果，此处不再进行赘述。
113.本领域普通技术人员可以理解，上文中所公开方法中的全部或某些步骤、系统、系统中的功能模块可以被实施为软件、固件、硬件及其适当的组合。在硬件实施方式中，在以上描述中提及的功能模块之间的划分不一定对应于物理组件的划分；例如，一个物理组件
可以具有多个功能，或者一个功能或步骤可以由若干物理组件合作执行。某些物理组件或所有物理组件可以被实施为由处理器，如中央处理器、数字信号处理器或微处理器执行的软件，或者被实施为硬件，或者被实施为集成电路，如专用集成电路。这样的软件可以分布在计算机可读介质上，计算机可读介质可以包括计算机存储介质(或非暂时性介质)和通信介质(或暂时性介质)。如本领域普通技术人员公知的，术语计算机存储介质包括在用于存储信息(诸如计算机可读指令、数据结构、程序模块或其它数据)的任何方法或技术中实施的易失性和非易失性、可移除和不可移除介质。计算机存储介质包括但不限于ram、rom、eeprom、闪存或其它存储器技术、cd-rom、数字多功能盘(dvd)或其它光盘存储、磁盒、磁带、磁盘存储或其它磁存储装置、或者可以用于存储期望的信息并且可以被计算机访问的任何其它的介质。此外，本领域普通技术人员公知的是，通信介质通常包含计算机可读指令、数据结构、程序模块或者诸如载波或其它传输机制之类的调制数据信号中的其它数据，并且可包括任何信息递送介质。
114.本文已经公开了示例实施例，并且虽然采用了具体术语，但它们仅用于并仅应当被解释为一般说明性含义，并且不用于限制的目的。在一些实例中，对本领域技术人员显而易见的是，除非另外明确指出，否则可单独使用与特定实施例相结合描述的特征、特性和/或元素，或可与其它实施例相结合描述的特征、特性和/或元件组合使用。因此，本领域技术人员将理解，在不脱离由所附的权利要求阐明的本公开的范围的情况下，可进行各种形式和细节上的改变。