CN103473045A - 一种生成接口文档的方法及装置 - Google Patents

Abstract

本发明公开了一种生成接口文档的方法及装置，属于计算机技术领域。所述方法包括：获取用户待查看接口对应的代码文件；在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及该接口属性信息对应的接口属性参数；根据所述接口注释代码，生成所述待查看接口对应的接口文档。本发明通过在用户查看接口时，获取待查看接口对应的代码文件，并从中获取到接口属性信息以及接口属性信息对应的接口属性参数。实现了对接口文档的动态生成，提高了生成接口文档的效率，并且提高了接口文档中内容的准确率。

Description

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

技术领域

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

背景技术

在应用开发的过程中，开发人员会根据测试或维护应用的需要，将开发应用时所使用的接口对应的各种属性信息，以及属性信息对应的属性参数等内容进行说明，并生成一份接口文档以便后期进行使用。其中，接口是同一系统的不同功能层之间的通信规则。

现有技术中生成接口文档的方式为：在应用的开发过程中，当编写时涉及到新的接口时，则在接口文档中以人工的方式写入该接口的各种属性、参数等接口说明；当某一个接口中所涉及的属性信息以及属性信息对应的属性参数进行修改时，则在接口文档中以人工的方式查找到该接口对应的接口说明，并进行对应的修改。

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

通过人工进行写入或修改的接口文档的方式，比较消耗时间，影响应用开发的进度；并且在接口更新或修改时，开发人员容易忽略对接口文档中对应的接口说明的更新，因此会造成接口文档中对接口的说明与代码中接口的属性信息以及属性信息对应的属性参数不符，而影响开发人员在应用开发后期的测试。

发明内容

为了解决现有技术的问题，本发明实施例提供了一种生成接口文档的方法及装置。

一方面，本发明提供了一种生成接口文档的方法，该方法包括：

获取用户待查看接口对应的代码文件；

在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及该接口属性信息对应的接口属性参数；

根据所述接口注释代码，生成所述待查看接口对应的接口文档。

优选的，所述获取用户待查看接口对应的代码文件，包括：

接收用户在接口配置文件中选取的待查看接口的接口标识；

在预先存储的接口标识与代码文件的路径信息的对应关系中，选取所述接口标识对应的代码文件的路径信息；

根据所述代码文件的路径信息，获取所述待查看接口对应的代码文件。

优选的，所述在所述代码文件中获取预设的接口注释代码，包括：

在所述代码文件的代码头中，查询注释代码标签；

将所述注释代码标签中的代码段确定为接口注释代码。

优选的，所述根据所述接口注释代码，生成所述待查看接口对应的接口文档，包括：

在所述接口注释代码中，获取预设的接口属性信息对应的接口属性参数；

将所述预设的接口属性信息对应的接口属性参数，添加入预先存储的接口文档模版中包含的与所述预设的接口属性信息相匹配的参数位置；

将添加了接口属性参数的接口文档模版确定为所述待查看接口对应的接口文档。

优选的，所述根据所述接口注释代码，生成所述待查看接口对应的接口文档之后，所述方法还包括：

获取所述待查看接口对应的测试用例代码，并将所述测试用例代码添加入所述待查看接口对应的接口文档中，其中所述测试用例代码用于根据对所述待查看接口进行测试使用。

另一方面，提供了一种生成接口文档的装置，所述装置包括：

第一获取模块，用于获取用户待查看接口对应的代码文件；

第二获取模块，用于在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及该接口属性信息对应的接口属性参数；

生成模块，用于根据所述接口注释代码，生成所述待查看接口对应的接口文档。

优选的，所述第一获取模块，包括：

接收单元，用于接收用户在接口配置文件中选取的待查看接口的接口标识；

选取单元，用于在预先存储的接口标识与代码文件的路径信息的对应关系中，选取所述接口标识对应的代码文件的路径信息；

第一获取单元，用于根据所述代码文件的路径信息，获取所述待查看接口对应的代码文件。

优选的，所述第二获取模块，包括：

查询单元，用于在所述代码文件的代码头中，查询注释代码标签；

第一确定单元，用于将所述注释代码标签中的代码段确定为接口注释代码。

优选的，所述生成模块，包括：

第二获取单元，用于在所述接口注释代码，获取预设的接口属性信息对应的接口属性参数；

添加单元，用于将所述预设的接口属性信息对应的接口属性参数，添加入预先存储的接口文档模版中包含的与所述预设的接口属性信息相匹配的参数位置；

第二确定单元，用于将添加了接口属性参数的接口文档模版确定为所述待查看接口对应的接口文档。

优选的，所述装置包括：

添加模块，用于获取所述待查看接口对应的测试用例代码，并将所述测试用例代码添加入所述待查看接口对应的接口文档中，其中所述测试用例代码用于根据对所述待查看接口进行测试使用。

本发明实施例提供的技术方案带来的有益效果是：

通过在用户查看接口时，获取待查看接口对应的代码文件，并从中获取到接口属性信息以及接口属性信息对应的接口属性参数。实现了对接口文档的动态生成，提高了生成接口文档的效率，并且提高了接口文档中内容的准确率。

附图说明

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

图1是本发明实施例一提供的生成接口文档的方法流程图；

图2是本发明实施例二提供的生成接口文档的方法流程图；

图3是本发明实施例三提供的生成接口文档的装置结构示意图。

具体实施方式

为使本发明的目的、技术方案和优点更加清楚，下面将结合附图对本发明实施方式作进一步地详细描述。

实施例一

本发明实施例提供了一种生成接口文档的方法，参见图1，方法流程包括：

101：获取用户待查看接口对应的代码文件；

102：在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及该接口属性信息对应的接口属性参数；

103：根据所述接口注释代码，生成所述待查看接口对应的接口文档。

本发明实施例通过在用户查看接口时，获取待查看接口对应的代码文件，并从中获取到接口属性信息以及接口属性信息对应的接口属性参数。实现了对接口文档的动态生成，提高了生成接口文档的效率，并且提高了接口文档中内容的准确率。

实施例二

本发明实施例提供了一种生成接口文档的方法，参见图2，方法流程包括：

201：获取用户待查看接口对应的代码文件。

其中，预先将代码中所涉及的接口保存在接口配置文件中，用户可以通过在该配置文件中进行选取需要查看的接口，此时系统会得到接口对应的接口标识，并通过预先存储的接口标识与代码文件的路径信息的对应关系，查询到用户选取的接口所在的代码文件。

其中，接口可以为接口函数，还可以为HTTP（HTTP-Hypertext transferprotocol，超文本传输协议）接口。

因此步骤201可以具体为：

2011：接收用户在接口配置文件中选取的待查看接口的接口标识。

其中，用户先打开接口配置文件，在其中选取需要查看的接口，此时系统会获取到用户选取的待查看接口的接口标识。例如：以HTTP接口中用户选择face_detect人脸识别接口为例。用户在接口配置文件中选取了该接口后，得到了该接口的接口标识：face_detect。

2012：在预先存储的接口标识与代码文件的路径信息的对应关系中，选取所述接口标识对应的代码文件的路径信息。

2013：根据所述代码文件的路径信息，获取所述待查看接口对应的代码文件。

从该路径信息对应的路径中，获取保存待查看接口的代码文件。

202：在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及所述接口属性信息对应的接口属性参数。

具体的，代码文件中包含了接口以及该接口对应的接口注释代码，其中接口注释代码中保存了对该接口的接口说明，其中包含了接口的属性信息以及属性信息对应的属性参数等内容。

因此，对于步骤202可以具体为：

2021：在所述代码文件的代码头中，查询注释代码标签。

对于HTTP接口，一般将接口注释代码保存在代码文件的代码头中。

例如：在PHP语言中，注释代码标签为：“/*......*/”，在这对标签中的内容即为注释代码。

2022：将所述注释代码标签中的代码段确定为接口注释代码。

其中对于接口注释代码，会根据不同的语言类型对应不同的注释代码标签，通过该注释代码标签，可以在代码文件中查找到接口注释代码。其中，接口注释代码的格式在HTTP接口中可以为JSON格式。

203：根据所述接口注释代码，生成所述待查看接口对应的接口文档。

在接口注释代码中保存有接口属性信息，以及接口属性信息对应的接口属性参数。

例如，在HTTP接口中，某接口的发送方式对应的接口属性信息为“Method”，该接口属性信息对应的接口属性参数为“post”，接口的描述对应的接口属性信息为“Description”，对应的接口属性参数为“detect faces rect in image”对应在接口注释代码中的具体内容为：

/*"Method"："post"

"Description"："detect faces rect in image"

*/

其中，接口属性信息一般为预先设定好的内容，其具体对应的接口属性参数会不同，因此通过预设的接口属性信息可以在接口注释代码中查询到这个接口中该接口属性信息对应的接口属性参数。进一步的，在HTTP接口中，接口属性信息还包括：输入属性信息“Input_Form_Data”，输出属性信息“Output_JSON”等接口属性信息。

因此步骤203可以具体为：

2031：在所述接口注释代码中，获取预设的接口属性信息对应的接口属性参数。

接口注释代码中预先保存有接口可能会涉及到的所有的接口属性信息，通过在接口注释代码中进行比对，获取到接口注释代码中存在的所有接口属性信息，并根据这些存在的接口属性信息获取到对应的接口属性参数。

2032：将所述预设的接口属性信息对应的接口属性参数，添加入预先存储的接口文档模版中包含的与所述预设的接口属性信息相匹配的参数位置。

其中，预先存储的接口文档模版中包含根据接口注释代码中存在的接口属性信息以及其对应的接口属性参数适应性生成的表格。具体的表格的格式为：在表格的第一列中为接口属性信息，第二列对应的位置为接口属性信息对应的接口属性参数，如表1所示：

接口属性信息	接口属性参数
		Method	post
Description	detect faces rect in image

表1

另一种情况，当接口属性信息为输入属性信息“Input_Form_Data”和输出属性信息“Output_JSON”时，其接口属性信息中的接口属性参数还有具体的值，例如：接口注释代码为：

其中，name为输入属性信息“Input_Form_Data”中的参数，app_id为name中的具体的值。因此这类接口属性信息可以在预先存储的接口文档模版中单独形成另一个表格，如表2所示：

表2

在预先存储的接口文档模版中，将步骤2031中获取到的预设的接口属性信息对应的接口属性参数，添加入与预设的接口属性信息相同的接口属性信息对应的参数位置。

2033：将添加了接口属性参数的接口文档模版确定为所述待查看接口对应的接口文档。

204：获取所述待查看接口对应的测试用例代码，并将所述测试用例代码添加入所述待查看接口对应的接口文档中，其中所述测试用例代码用于根据对所述待查看接口进行测试使用。

其中，可以预先保存接口对应的测试用例，并在生成的接口文档中将该测试用例显示在接口文档中，用于当用户查看接口文档时，进行调用和学习使用。

进一步的，用户查看接口文档后，该接口文档并不进行保存，本发明实施例中的接口文档是根据用户的查看而生成的。

本发明实施例通过在用户查看接口时，获取待查看接口对应的代码文件，并从中获取到接口属性信息以及接口属性信息对应的接口属性参数。实现了对接口文档的动态生成，提高了生成接口文档的效率，并且提高了接口文档中内容的准确率。

实施例三

本发明实施例提供了一种生成接口文档的装置，参见图3，该装置包括：

第一获取模块301，用于获取用户待查看接口对应的代码文件；

第二获取模块302，用于在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及该接口属性信息对应的接口属性参数；

生成模块303，用于根据所述接口注释代码，生成所述待查看接口对应的接口文档。

其中，所述第一获取模块301，包括：

接收单元，用于接收用户在接口配置文件中选取的待查看接口的接口标识；

选取单元，用于在预先存储的接口标识与代码文件的路径信息的对应关系中，选取所述接口标识对应的代码文件的路径信息；

第一获取单元，用于根据所述代码文件的路径信息，获取所述待查看接口对应的代码文件。

其中，所述第二获取模块302，包括：

查询单元，用于在所述代码文件的代码头中，查询注释代码标签；

第一确定单元，用于将所述注释代码标签中的代码段确定为接口注释代码。

其中，所述生成模块303，包括：

第二获取单元，用于在所述接口注释代码，获取预设的接口属性信息对应的接口属性参数；

添加单元，用于将所述预设的接口属性信息对应的接口属性参数，添加入预先存储的接口文档模版中包含的与所述预设的接口属性信息相匹配的参数位置；

第二确定单元，用于将添加了接口属性参数的接口文档模版确定为所述待查看接口对应的接口文档。

其中，所述装置还包括：

添加模块304，用于获取所述待查看接口对应的测试用例代码，并将所述测试用例代码添加入所述待查看接口对应的接口文档中，其中所述测试用例代码用于根据对所述待查看接口进行测试使用。

本发明实施例通过在用户查看接口时，获取待查看接口对应的代码文件，并从中获取到接口属性信息以及接口属性信息对应的接口属性参数。实现了对接口文档的动态生成，提高了生成接口文档的效率，并且提高了接口文档中内容的准确率。

上述本发明实施例序号仅仅为了描述，不代表实施例的优劣。

本领域普通技术人员可以理解实现上述实施例的全部或部分步骤可以通过硬件来完成，也可以通过程序来指令相关的硬件完成，所述的程序可以存储于一种计算机可读存储介质中，上述提到的存储介质可以是只读存储器，磁盘或光盘等。

以上所述仅为本发明的较佳实施例，并不用以限制本发明，凡在本发明的精神和原则之内，所作的任何修改、等同替换、改进等，均应包含在本发明的保护范围之内。

Claims (10)

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

获取用户待查看接口对应的代码文件；

在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及该接口属性信息对应的接口属性参数；

根据所述接口注释代码，生成所述待查看接口对应的接口文档。

2.根据权利要求1所述的方法，其特征在于，所述获取用户待查看接口对应的代码文件，包括：

接收用户在接口配置文件中选取的待查看接口的接口标识；

在预先存储的接口标识与代码文件的路径信息的对应关系中，选取所述接口标识对应的代码文件的路径信息；

根据所述代码文件的路径信息，获取所述待查看接口对应的代码文件。

3.根据权利要求1所述的方法，其特征在于，所述在所述代码文件中获取接口注释代码，包括：

在所述代码文件的代码头中，查询注释代码标签；

将所述注释代码标签中的代码段确定为接口注释代码。

4.根据权利要求1所述的方法，其特征在于，所述根据所述接口注释代码，生成所述待查看接口对应的接口文档，包括：

在所述接口注释代码中，获取预设的接口属性信息对应的接口属性参数；

将所述预设的接口属性信息对应的接口属性参数，添加入预先存储的接口文档模版中包含的与所述预设的接口属性信息相匹配的参数位置；

将添加了接口属性参数的接口文档模版确定为所述待查看接口对应的接口文档。

5.根据权利要求1或4所述的方法，其特征在于，所述根据所述接口注释代码，生成所述待查看接口对应的接口文档之后，所述方法还包括：

获取所述待查看接口对应的测试用例代码，并将所述测试用例代码添加入所述待查看接口对应的接口文档中，其中所述测试用例代码用于对所述待查看接口进行测试使用。

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

第一获取模块，用于获取用户待查看接口对应的代码文件；

第二获取模块，用于在所述代码文件中获取接口注释代码，其中所述接口注释代码中保存有所述待查看接口的接口属性信息以及该接口属性信息对应的接口属性参数；

生成模块，用于根据所述接口注释代码，生成所述待查看接口对应的接口文档。

7.根据权利要求6所述的装置，其特征在于，所述第一获取模块，包括：

接收单元，用于接收用户在接口配置文件中选取的待查看接口的接口标识；

选取单元，用于在预先存储的接口标识与代码文件的路径信息的对应关系中，选取所述接口标识对应的代码文件的路径信息；

第一获取单元，用于根据所述代码文件的路径信息，获取所述待查看接口对应的代码文件。

8.根据权利要求6所述的装置，其特征在于，所述第二获取模块，包括：

查询单元，用于在所述代码文件的代码头中，查询注释代码标签；

第一确定单元，用于将所述注释代码标签中的代码段确定为接口注释代码。

9.根据权利要求6所述的装置，其特征在于，所述生成模块，包括：

第二获取单元，用于在所述接口注释代码，获取预设的接口属性信息对应的接口属性参数；

添加单元，用于将所述预设的接口属性信息对应的接口属性参数，添加入预先存储的接口文档模版中包含的与所述预设的接口属性信息相匹配的参数位置；

第二确定单元，用于将添加了接口属性参数的接口文档模版确定为所述待查看接口对应的接口文档。

10.根据权利要求6或9所述的装置，其特征在于，所述装置还包括：

添加模块，用于获取所述待查看接口对应的测试用例代码，并将所述测试用例代码添加入所述待查看接口对应的接口文档中，其中所述测试用例代码用于根据对所述待查看接口进行测试使用。

Images