CN108762808B - 接口文档的生成方法及系统 - Google Patents

Abstract

本发明公开了一种接口文档的生成方法及系统，通过利用Javadoc的doclet技术，从源代码中解析出服务接口信息；根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；将生成的所述接口文档上传至文档管理数据库，以供查询；具有无需手动编写配置文件且无需额外引入注解来标记接口、即可自动生成对应的接口文档的有益效果，提高了系统开发效率；进一步地，由于无需引入额外的注解或者注释来标记接口，避免了因引入额外注释来标记接口而对原有系统所造成的侵入性。

Description

接口文档的生成方法及系统

技术领域

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

背景技术

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

发明内容

本发明提供一种接口文档的生成方法及系统，旨在利用代码解析技术，无需手动编写配置文件且无需额外引入注解来标记接口，即可自动生成对应的接口文档，提高开发效率。

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

利用Javadoc的doclet技术，从源代码中解析出服务接口信息；

根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；

将生成的所述接口文档上传至文档管理数据库，以供查询。

进一步地，所述利用Javadoc的doclet技术，从源代码中解析出服务接口信息，包括：

利用Javadoc的doclet技术，不强制对被解析的源代码添加注释或者接口标注，识别出源代码中所使用的服务框架；

基于使用的所述服务框架，解析所述源代码中的服务接口以及所述服务接口对应的相关参数，得到对应的服务接口信息。

进一步地，所述从源代码中解析出的服务接口信息包括：所述服务接口对应的注释以及所述服务接口对应的输入参数和输出参数；

根据解析出的所述输入参数和输出参数，按照所述服务接口对应的注释，完善对应的接口文档；

其中，所述注释无需被解析的所述源代码引入对应的类库。

进一步地，所述将生成的所述接口文档上传至文档管理数据库，包括：

根据所述服务接口信息，删除已上传的相同属性的接口文档，保留最新上传的所述相同属性对应的接口文档；

其中，所述相同属性包括：相同的系统名称、相同的版本号和相同的接口地址。

进一步地，所述为每个服务接口生成对应的接口文档，包括：

获取所述服务接口信息中的所有的返回参数，并确定每个所述返回参数的字符信息；

分别根据所述返回参数的字符信息生成与所述返回参数相应的字符数组Xⁱ，且

其中，xⁱ _j为第i个字符数组中的第j个元素值，n_i为第i个返回参数的字符总数，i∈[1，m]，m为返回参数的总数量；

将所述字符数组中前三个元素相同的字符数组归为一个参数集合，并遍历确定所述参数集合中字符数组的相同元素以及相同元素个数p，p≥3；

根据p个相同元素的元素值确定所述参数集合的权重系数W^k，并根据参数集合的权重系数W^k确定参数集合排列顺序；其中，第k个参数集合的权重系数W^k为：

其中，

j∈[1，p]，第i个字符数组属于第k个参数集合，且xⁱ ₀＝0；

依次确定第k个参数集合中每个字符数组的权重值，并根据字符数组的权重值对所述第k个参数集合的所有字符数组进行排序，确定所述第k个参数集合的字符数组排列顺序；其中，第i个字符数组的权重值w_i为：

当第l个字符数组不属于任何一个参数集合时，根据第l个字符数组的权重值对第l个字符数组进行排序，确定所有不属于任何参数集合的字符数组排列顺序；其中，第l个字符数组的权重值w₁为：

n₁为第l个返回参数的字符总数，且x^l ₀＝0；

根据所述参数集合排列顺序、每个参数集合的字符数组排列顺序以及不属于任何参数集合的字符数组排列顺序确定所有返回参数的排列顺序，并根据所述返回参数的排列顺序依次展示所有的返回参数。

进一步地，所述接口文档的生成方法还包括：

为已上传的所述接口文档建立索引；

接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示：

所述接口文档的生成方法还包括：

对已索引的所述接口文档进行更新和维护。

对应于上述实施例所提供的一种接口文档的生成方法，本发明实施例还提供了一种接口文档的生成系统，所述接口文档的生成系统包括：

解析模块，用于利用Javadoc的doclet技术，从源代码中解析出服务接口信息；

生成模块，用于根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；

上传模块，用于将生成的所述接口文档上传至文档管理数据库，以供查询。

进一步地，所述解析模块用于：

利用Javadoc的doclet技术，不强制对被解析的源代码添加注释或者接口标注，识别出源代码中所使用的服务框架；

基于使用的所述服务框架，解析所述源代码中的服务接口以及所述服务接口对应的相关参数，得到对应的服务接口信息。

进一步地，所述解析模块从源代码中解析出的服务接口信息包括：所述服务接口对应的注释以及所述服务接口对应的输入参数和输出参数；

所述生成模块用于：根据解析出的所述输入参数和输出参数，按照所述服务接口对应的注释，完善对应的接口文档；

其中，所述注释无需被解析的所述源代码引入对应的类库。

进一步地，所述上传模块用于：

根据所述服务接口信息，删除已上传的相同属性的接口文档，保留最新上传的所述相同属性对应的接口文档；

其中，所述相同属性包括：相同的系统名称、相同的版本号和相同的接口地址。

进一步地，所述生成模块用于：

获取所述服务接口信息中的所有的返回参数，并确定每个所述返回参数的字符信息；

分别根据所述返回参数的字符信息生成与所述返回参数相应的字符数组Xⁱ，且

其中，xⁱ _j为第i个字符数组中的第j个元素值，n_i为第i个返回参数的字符总数，i∈[1，m]，m为返回参数的总数量；

将所述字符数组中前三个元素相同的字符数组归为一个参数集合，并遍历确定所述参数集合中字符数组的相同元素以及相同元素个数p，p≥3；

根据p个相同元素的元素值确定所述参数集合的权重系数W^k，并根据参数集合的权重系数W^k确定参数集合排列顺序；其中，第k个参数集合的权重系数W^k为：

其中，

j∈[1，p]，第i个字符数组属于第k个参数集合，且xⁱ ₀＝0；

依次确定第k个参数集合中每个字符数组的权重值，并根据字符数组的权重值对所述第k个参数集合的所有字符数组进行排序，确定所述第k个参数集合的字符数组排列顺序；其中，第i个字符数组的权重值wi为：

当第l个字符数组不属于任何一个参数集合时，根据第l个字符数组的权重值对第l个字符数组进行排序，确定所有不属于任何参数集合的字符数组排列顺序；其中，第l个字符数组的权重值w₁为：

n₁为第l个返回参数的字符总数，且x^l ₀＝0；

根据所述参数集合排列顺序、每个参数集合的字符数组排列顺序以及不属于任何参数集合的字符数组排列顺序确定所有返回参数的排列顺序，并根据所述返回参数的排列顺序依次展示所有的返回参数。

进一步地，所述接口文档的生成系统还包括：

索引模块，用于为已上传的所述接口文档建立索引；

搜索模块，用于接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示；

管理模块，用于对已索引的所述接口文档进行更新和维护。

本发明一种接口文档的生成方法及系统可以达到如下有益效果：

通过利用Javadoc的doclet技术，从源代码中解析出服务接口信息；根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；将生成的所述接口文档上传至文档管理数据库，以供查询；具有无需手动编写配置文件且无需额外引入注解来标记接口、即可自动生成对应的接口文档的有益效果，提高了系统开发效率；进一步地，由于无需引入额外的注解或者注释来标记接口，避免了因引入额外注释来标记接口而对原有系统所造成的侵入性；另外，通过为已上传的所述接口文档建立索引，接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示；具有提高信息一致性的有益效果，实现了接口开发方与接口使用方的信息一致性。通过对返回参数进行多级排序实现对返回参数的精确排序，以三个元素作为分组基准，在提高分组效率的同时还可以保证分组的准确性；基于调整系数对参数集合的权重系数进行归一化处理，使得最终确定的权重系数与靠前的元素更加相关，参数集合的排序更加符合实际情况；基于字符数组的面积之和对字符数组进行排序，使得字符数组的顺序与元素个数和元素值相关，同时可以保证排序结果的准确性。

本发明的其它特征和优点将在随后的说明书中阐述，并且，部分地从说明书中变得显而易见，或者通过实施本发明而了解。本发明的目的和其他优点可通过在所写的说明书、权利要求书、以及附图中所指出的内容来实现和获得。

下面通过附图和实施例，对本发明的技术方案做进一步描述。

附图说明

附图用来提供对本发明的进一步理解，并且构成说明书的一部分，与本发明的实施例一起用于解释本发明，并不构成对本发明的限制。在附图中：

图1是本发明接口文档的生成方法的一种实施方式的流程示意图；

图2是本发明接口文档的生成方法的另一种实施方式的流程示意图；

图3是本发明接口文档的生成方法中对返回参数进行排序的流程示意图；

图4是本发明接口文档的生成系统的一种实施方式的功能模块示意图；

图5是本发明接口文档的生成系统的另一种实施方式的功能模块示意图。

具体实施方式

以下结合附图对本发明的优选实施例进行说明，应当理解，此处所描述的优选实施例仅用于说明和解释本发明，并不用于限定本发明。

本发明提供了一种接口文档的生成方法及系统，旨在利用代码解析技术，无需手动编写配置文件且无需额外引入注解来标记接口，即可自动生成对应的接口文档，提高开发效率。

如图1所示，图1是本发明接口文档的生成方法的一种实施方式的流程示意图；本发明一种接口文档的生成方法，针对手工编写接口文档容易出现与实际接口文档不一致的情况，采用代码解析技术，自动生成对应的接口文档，确保了代码与接口文档的一致性。其中，本发明实施例中所描述的代码解析技术，主要采用了Javadoc的doclet技术，通过doclet技术获取到源代码的所有的类信息，根据现有服务的规范(比如Spring MVC、SOAPService、Dubbo等)，分析出源代码所对应的服务接口，并进一步生成接口文档。

所描述的doclet技术可以理解为：采用JavaTM编程语言编写的程序，它用docletAPI(Application Programming Interface，应用程序编程接口)指定Javadoc工具的输出内容和格式；在缺省情况下，Javadoc工具用SunTM提供的“标准”doclet来生成HTML形式的API文档。当然，用户也可用自己的doclet根据个人喜好自定义Javadoc输出；比如，用户可以利用doclet API从头开始编写doclet，也可以对标准doclet进行修改，以适合自己的需要。

基于以上描述，请参照图1，本发明接口文档的生成方法可以实施为如下描述的步骤S10-S30：

步骤S10、利用Javadoc的doclet技术，从源代码中解析出服务接口信息；

接口文档的生成系统(以下简称“生成系统”)利用Javadoc的doclet技术，对源代码进行解析，在解析的过程中，生成系统对被解析的源代码不强制要求添加注释，也不强制要求使用者提供配置文件来标注接口，如此一来，避免了因引入额外的注解来标记接口、从而对原有系统所造成的侵入性。

根据识别出的服务框架，生成系统解析上述源代码中的服务接口以及所述服务接口对应的相关参数，得到对应的服务接口信息；上述服务接口信息包括但不限于：服务接口对应的类名、类变量、类方法、方法参数、注释和注解，以及服务接口对应的输入参数和输出参数等。

步骤S20、根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；

生成系统根据解析出的上述服务接口信息，自动为每个服务接口生成对应的接口文档。进一步地，根据解析出的服务接口信息中的输入参数和输出参数，按照所述服务接口对应的注释，完善对应的接口文档。其中，所述注释无需被解析的所述源代码引入对应的类库。

生成系统自动生成的接口文档的信息，包括但不限于：服务接口地址、接口描述信息、接口的输入输出参数和返回码信息、接口参数是否必须以及接口的变更历史信息。另外，生成系统自动生成的接口文档中同时包含了接口的元信息，比如，接口标签、接口所属的系统名称和版本号以及接口地址等。在一具体的应用场景中，生成系统生成的接口文档可以为HTML文档，该格式的文档可以被独立浏览查看。

步骤S30、将生成的所述接口文档上传至文档管理数据库，以供查询。

为了便于后续对接口文档进行查询，生成系统将生成的上述接口文档上传至文档管理数据库，以便对该接口文档进行统一管理。

进一步地，针对最新上传的接口文档，生成系统根据该接口文档对应的服务接口信息，查找文档管理数据库中是否已存在与该最新上传的接口文档相同属性的旧接口文档；若存在与最新上传的接口文档相同属性的旧接口文档，则将已存在的旧接口文档进行删除，仅保留最新上传的该接口文档。若不存在与最新上传的接口文档相同属性的旧接口文档，则直接保留该最新上传的接口文档即可。本发明实施例中，所描述的接口文档的相同属性包括：接口文档对应的系统名称、版本号和接口地址均相同。

本发明接口文档的生成方法通过利用Javadoc的doclet技术，从源代码中解析出服务接口信息；根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；将生成的所述接口文档上传至文档管理数据库，以供查询；具有无需手动编写配置文件且无需额外引入注解来标记接口、即可自动生成对应的接口文档的有益效果，提高了系统开发效率；进一步地，由于无需引入额外的注解或者注释来标记接口，避免了因引入额外注释来标记接口而对原有系统所造成的侵入性。

基于以上实施例的描述，请参照图2，图2是本发明接口文档的生成方法的另一种实施方式的流程示意图；本发明一种接口文档的生成方法，针对生成系统对接口文档缺少统一的管理和查询，容易出现开发者更新了接口文档后不能发送通知到所有使用方，导致接口开发方与接口使用方信息不一致的情况，提出生成系统对接口文档的管理功能。在接口文档生成后，利用生成系统的文档上传管理功能，将生成好的接口文档上传至对应文档索引对应的索引模块。接口文档使用方在需要阅读接口文档时，通过互联网浏览器访问该生成系统对应的具备文档查询展示的搜索模块，具备文档查询展示的搜索模块直接通过索引模块获取使用方需要访问的接口文档并展示。

如图2所示，本发明接口文档的生成方法还包括如下描述的步骤S21-S22：

步骤S21、为已上传的所述接口文档建立索引；

步骤S22、接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示。

进一步地，在本发明一优选的实施例中，生成系统针对已上传并已建立索引的接口文档，对已索引的上述接口文档进行更新和维护。比如，针对已索引的接口文档，生成系统新增加索引接口文档，或者删除相同属性的旧接口文档，或者更新已索引的接口文档对应的索引地址等。

本发明接口文档的生成方法通过为已上传的所述接口文档建立索引，接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示；具有提高信息一致性的有益效果，实现了接口开发方与接口使用方的信息一致性。

基于以上实施例的描述，本发明实施例提供的一种接口文档的生成方法，针对返回参数较多时排序混乱、导致开发者不易快速定位至所需的返回参数的情况，提出对返回参数进行分级排序的功能，通过对返回参数进行分级排序实现对返回参数的精确排序。

如图3所示，本发明实施例中为每个服务接口生成对应的接口文档包括对返回参数进行排序的过程，该过程具体包括步骤S31-S37：

步骤S31、获取服务接口信息中的所有的返回参数，并确定每个返回参数的字符信息。

本发明实施例中，服务接口信息中具体包括：接口定义方法、接口uri(UniformResource Identifier，统一资源标识符)、请求参数、返回参数等，其中，返回参数有时候会存在数量较多的情况。当返回参数数量较多时，通过对返回参数排序来增加返回参数的有序性，方便用户快速查阅相对应的返回参数。其中，每个返回参数均由一个或多个字符组成，且每个返回参数的字符信息代表某一种含义，例如：usemame表示用户名，hobbybook表示喜欢的书籍等。

步骤S32、分别根据返回参数的字符信息生成与返回参数相应的字符数组Xⁱ，且

其中，xⁱ _j为第i个字符数组中的第j个元素值，ni为第i个返回参数的字符总数，i∈[1，m]，m为返回参数的总数量。

其中，预设字符与数值之间的对应关系，例如a对应1，b对应2等，根据预设的字符与数值之间的对应关系可以确定返回参数的字符数组。例如，a～z依次对应1～26，则返回参数“username”的字符数组为：Xⁱ＝[21，19，5，18，14，1，13，5]；对于该字符数组Xⁱ，字符总数n_i＝8。假设返回参数共10个，则m＝10。

步骤S33、将字符数组中前三个元素相同的字符数组归为一个参数集合，并遍历确定参数集合中字符数组的相同元素以及相同元素个数p，p≥3。

由于一般部分返回参数会有相同的前缀，可以根据返回参数的前缀对返回参数进行分组。本发明实施例中，由于一般返回参数的前缀的字符数均大于等于3，故以前三个元素作为分组基准，同时，以三个元素作为基准也可以有效避免分组错误的情况，在提高分组效率的同时也可以保证分组的准确性。同时，本发明实施例中的“遍历”字符数组的含义是从头到尾遍历字符数组中的元素，知道元素不同为止。例如，返回参数有username，useraddress(用户地址)、hobbybook、usemumber(用户号码)，则usemame、useraddress、usernumber属于同一个参数集合，且所有的字符数组均具有相同的前缀user，即相同元素为user，且相同元素个数p＝4。

步骤S34、根据p个相同元素的元素值确定参数集合的权重系数W^k，并根据参数集合的权重系数W^k确定参数集合排列顺序；其中，第k个参数集合的权重系数W^k为：

其中，

j∈[1，p]，第i个字符数组属于第k个参数集合，且xⁱ ₀＝0。

本发明实施例中，根据参数集合的相同前缀确定参数集合的权重系数。其中，在确定第k个参数集合的权重系数W^k时引入调整系数w^k _j，且随着j增大，调整系数减小，使得靠前的相同元素具有较大的权重，使得最终确定的权重系数W^k与靠前的元素更加相关。同时所有调整系数之和为：

即所有调整系数之和为1，从而可以避免因不同参数集合具有不同元素个数p时导致权重系数不具有统一数量级的问题，利用调整系数对权重系数进行归一化处理。

步骤S35、依次确定第k个参数集合中每个字符数组的权重值，并根据字符数组的权重值对第k个参数集合的所有字符数组进行排序，确定第k个参数集合的字符数组排列顺序；其中，第i个字符数组的权重值w_i为：

本发明实施例中，对于一个字符数组，以字符元素的序号为x轴，以元素值为y轴，则

表示第j-1个元素与第j个元素之间以及x轴所围绕形成的梯形(或三角形)的面积，面积越大，说明元素个数越多或者元素值越大(即元素排序更靠后)；故，第i个字符数组的权重值w_i越大，说明第i个字符数组的元素个数越多或者元素值越大，此时可以相对的靠后排列。即，第k个参数集合中按照字符数组权重值从小到大的顺序进行排列，生成第k个参数集合的字符数组排列顺序。

步骤S36、当第l个字符数组不属于任何一个参数集合时，根据第l个字符数组的权重值对第l个字符数组进行排序，确定所有不属于任何参数集合的字符数组排列顺序；其中，第l个字符数组的权重值w1为：

n_l为第l个返回参数的字符总数，且x^l ₀＝0。

本发明实施例中，由于可能存在部分返回参数没有相同前缀的情况，此时按照步骤S36中确定字符数组的权重值来对所有没有相同前缀(即不属于任何一个参数集合)的返回参数进行排序。其中，w₁与w_i的本质相同，均可以表示字符数组对应的面积之和。

步骤S37、根据参数集合排列顺序、每个参数集合的字符数组排列顺序以及不属于任何参数集合的字符数组排列顺序确定所有返回参数的排列顺序，并根据返回参数的排列顺序依次展示所有的返回参数。

本发明实施例中，首先对所有返回参数进行分组，确定参数集合，并对参数集合进行排序(一级排序)，之后对每个参数集合分别进行字符数组排序(二级排序)，从而可以初步生成返回参数的排序；对于不属于任何参数集合的字符数组，可以将不属于任何参数集合的字符数组作为一个特殊的参数集合，将该特殊的参数集合放置与其他参数集合的前面(或者后面)，从而生成所有返回参数的排列顺序。

本发明实施例中，通过对返回参数进行多级排序实现对返回参数的精确排序，以三个元素作为分组基准，在提高分组效率的同时还可以保证分组的准确性；基于调整系数对参数集合的权重系数进行归一化处理，使得最终确定的权重系数与靠前的元素更加相关，参数集合的排序更加符合实际情况；基于字符数组的面积之和对字符数组进行排序，使得字符数组的顺序与元素个数和元素值相关，同时可以保证排序结果的准确性。

需要说明的是，本发明实施例中的j仅用于表示数量，在不同的式子中可能有不同的取值范围，具体由式子本身决定。

对应于以上实施例所描述的一种接口文档的生成方法，本发明实施例还提供了一种接口文档的生成系统；该接口文档的生成系统可以实施上述接口文档的生成方法所对应的所有操作，且具备上述接口文档的生成方法的所有操作所带来的有益效果，在后续针对接口文档的生成系统的实施例中，对于上述内容不进行一一赘述。

如图4所示，图4是本发明接口文档的生成系统的一种实施方式的功能模块示意图；本发明接口文档的生成系统包括：解析模块100、生成模块200以及上传模块300；其中：

解析模块100，用于利用Javadoc的doclet技术，从源代码中解析出服务接口信息；

生成模块200，用于根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；

上传模块300，用于将生成的所述接口文档上传至文档管理数据库，以供查询。

在本发明一优选的实施例中，所述解析模块100用于：

利用Javadoc的doclet技术，不强制对被解析的源代码添加注释或者接口标注，识别出源代码中所使用的服务框架；

基于使用的所述服务框架，解析所述源代码中的服务接口以及所述服务接口对应的相关参数，得到对应的服务接口信息。

在本发明一优选的实施例中，所述解析模块100从源代码中解析出的服务接口信息包括：所述服务接口对应的注释以及所述服务接口对应的输入参数和输出参数；

所述生成模块200用于：根据解析出的所述输入参数和输出参数，按照所述服务接口对应的注释，完善对应的接口文档；

其中，所述注释无需被解析的所述源代码引入对应的类库。

在本发明一优选的实施例中，所述上传模块300用于：

根据所述服务接口信息，删除已上传的相同属性的接口文档，保留最新上传的所述相同属性对应的接口文档；

其中，所述相同属性包括：相同的系统名称、相同的版本号和相同的接口地址。

本发明接口文档的生成系统通过利用Javadoc的doclet技术，从源代码中解析出服务接口信息；根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；将生成的所述接口文档上传至文档管理数据库，以供查询；具有无需手动编写配置文件且无需额外引入注解来标记接口、即可自动生成对应的接口文档的有益效果，提高了系统开发效率；进一步地，由于无需引入额外的注解或者注释来标记接口，避免了因引入额外注释来标记接口而对原有系统所造成的侵入性。

基于以上实施例的描述，如图5所示，图5是本发明接口文档的生成系统的另一种实施方式的功能模块示意图；本发明接口文档的生成系统还包括：索引模块400、搜索模块500以及管理模块600；其中：

索引模块400，用于为已上传的所述接口文档建立索引；

搜索模块500，用于接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示；

管理模块600，用于对已索引的所述接口文档进行更新和维护。

本发明接口文档的生成系统通过为已上传的所述接口文档建立索引，接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示；具有提高信息一致性的有益效果，实现了接口开发方与接口使用方的信息一致性。

本领域内的技术人员应明白，本发明的实施例可提供为方法、系统、或计算机程序产品。因此，本发明可采用完全硬件实施例、完全软件实施例、或结合软件和硬件方面的实施例的形式。

本发明是参照根据本发明实施例的方法、设备(系统)、和计算机程序产品的流程图和/或方框图来描述的。应理解可由计算机程序指令实现流程图和/或方框图中的每一流程和/或方框、以及流程图和/或方框图中的流程和/或方框的结合。可提供这些计算机程序指令到通用计算机、专用计算机、嵌入式处理机或其他可编程数据处理设备的处理器以产生一个机器，使得通过计算机或其他可编程数据处理设备的处理器执行的指令产生用于实现在流程图一个流程或多个流程和/或方框图一个方框或多个方框中指定的功能的装置。

这些计算机程序指令也可存储在能引导计算机或其他可编程数据处理设备以特定方式工作的计算机可读存储器中，使得存储在该计算机可读存储器中的指令产生包括指令装置的制造品，该指令装置实现在流程图一个流程或多个流程和/或方框图一个方框或多个方框中指定的功能。

这些计算机程序指令也可装载到计算机或其他可编程数据处理设备上，使得在计算机或其他可编程设备上执行一系列操作步骤以产生计算机实现的处理，从而在计算机或其他可编程设备上执行的指令提供用于实现在流程图一个流程或多个流程和/或方框图一个方框或多个方框中指定的功能的步骤。

显然，本领域的技术人员可以对本发明进行各种改动和变型而不脱离本发明的精神和范围。这样，倘若本发明的这些修改和变型属于本发明权利要求及其等同技术的范围之内，则本发明也意图包含这些改动和变型在内。

Claims (10)

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

利用Javadoc的doclet技术，从源代码中解析出服务接口信息；

根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；

将生成的所述接口文档上传至文档管理数据库，以供查询；

所述为每个服务接口生成对应的接口文档，包括：

获取所述服务接口信息中的所有的返回参数，并确定每个所述返回参数的字符信息；

分别根据所述返回参数的字符信息生成与所述返回参数相应的字符数组Xⁱ，且

其中，xⁱ _j为第i个字符数组中的第j个元素值，n_i为第i个返回参数的字符总数，i∈[1,m]，m为返回参数的总数量；

将所述字符数组中前三个元素相同的字符数组归为一个参数集合，并遍历确定所述参数集合中字符数组的相同元素以及相同元素个数p，p≥3；

根据p个相同元素的元素值确定所述参数集合的权重系数W^k，并根据参数集合的权重系数W^k确定参数集合排列顺序；其中，第k个参数集合的权重系数W^k为：

其中，

第i个字符数组属于第k个参数集合，且xⁱ ₀＝0；

依次确定第k个参数集合中每个字符数组的权重值，并根据字符数组的权重值对所述第k个参数集合的所有字符数组进行排序，确定所述第k个参数集合的字符数组排列顺序；其中，第i个字符数组的权重值w_i为：

当第l个字符数组不属于任何一个参数集合时，根据第l个字符数组的权重值对第l个字符数组进行排序，确定所有不属于任何参数集合的字符数组排列顺序；其中，第l个字符数组的权重值w_l为：

n_l为第l个返回参数的字符总数，且x^l ₀＝0；

根据所述参数集合排列顺序、每个参数集合的字符数组排列顺序以及不属于任何参数集合的字符数组排列顺序确定所有返回参数的排列顺序，并根据所述返回参数的排列顺序依次展示所有的返回参数。

2.如权利要求1所述的接口文档的生成方法，其特征在于，所述利用Javadoc的doclet技术，从源代码中解析出服务接口信息，包括：

利用Javadoc的doclet技术，适应性地对被解析的源代码添加注释或者接口标注，识别出源代码中所使用的服务框架；

基于使用的所述服务框架，解析所述源代码中的服务接口以及所述服务接口对应的相关参数，得到对应的服务接口信息。

3.如权利要求1所述的接口文档的生成方法，其特征在于，所述从源代码中解析出的服务接口信息包括：所述服务接口对应的注释以及所述服务接口对应的输入参数和输出参数；

根据解析出的所述输入参数和输出参数，按照所述服务接口对应的注释，完善对应的接口文档；

其中，所述注释无需被解析的所述源代码引入对应的类库。

4.如权利要求1所述的接口文档的生成方法，其特征在于，所述将生成的所述接口文档上传至文档管理数据库，包括：

根据所述服务接口信息，删除已上传的相同属性的接口文档，保留最新上传的所述相同属性对应的接口文档；

其中，所述相同属性包括：相同的系统名称、相同的版本号和相同的接口地址。

5.如权利要求1至4任一项所述的接口文档的生成方法，其特征在于，所述接口文档的生成方法还包括：

为已上传的所述接口文档建立索引；

接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示；

所述接口文档的生成方法还包括：

对已索引的所述接口文档进行更新和维护。

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

解析模块，用于利用Javadoc的doclet技术，从源代码中解析出服务接口信息；

生成模块，用于根据解析出的服务接口信息，为每个服务接口生成对应的接口文档；

上传模块，用于将生成的所述接口文档上传至文档管理数据库，以供查询；

所述生成模块用于：

获取所述服务接口信息中的所有的返回参数，并确定每个所述返回参数的字符信息；

分别根据所述返回参数的字符信息生成与所述返回参数相应的字符数组Xⁱ，且

其中，xⁱ _j为第i个字符数组中的第j个元素值，n_i为第i个返回参数的字符总数，i∈[1,m]，m为返回参数的总数量；

将所述字符数组中前三个元素相同的字符数组归为一个参数集合，并遍历确定所述参数集合中字符数组的相同元素以及相同元素个数p，p≥3；

根据p个相同元素的元素值确定所述参数集合的权重系数W^k，并根据参数集合的权重系数W^k确定参数集合排列顺序；其中，第k个参数集合的权重系数W^k为：

其中，

第i个字符数组属于第k个参数集合，且xⁱ ₀＝0；

依次确定第k个参数集合中每个字符数组的权重值，并根据字符数组的权重值对所述第k个参数集合的所有字符数组进行排序，确定所述第k个参数集合的字符数组排列顺序；其中，第i个字符数组的权重值w_i为：

当第l个字符数组不属于任何一个参数集合时，根据第l个字符数组的权重值对第l个字符数组进行排序，确定所有不属于任何参数集合的字符数组排列顺序；其中，第l个字符数组的权重值w_l为：

n_l为第l个返回参数的字符总数，且x^l ₀＝0；

根据所述参数集合排列顺序、每个参数集合的字符数组排列顺序以及不属于任何参数集合的字符数组排列顺序确定所有返回参数的排列顺序，并根据所述返回参数的排列顺序依次展示所有的返回参数。

7.如权利要求6所述的接口文档的生成系统，其特征在于，所述解析模块用于：

利用Javadoc的doclet技术，适应性地对被解析的源代码添加注释或者接口标注，识别出源代码中所使用的服务框架；

基于使用的所述服务框架，解析所述源代码中的服务接口以及所述服务接口对应的相关参数，得到对应的服务接口信息。

8.如权利要求6所述的接口文档的生成系统，其特征在于，所述解析模块从源代码中解析出的服务接口信息包括：所述服务接口对应的注释以及所述服务接口对应的输入参数和输出参数；

所述生成模块用于：根据解析出的所述输入参数和输出参数，按照所述服务接口对应的注释，完善对应的接口文档；

其中，所述注释无需被解析的所述源代码引入对应的类库。

9.如权利要求6所述的接口文档的生成系统，其特征在于，所述上传模块用于：

根据所述服务接口信息，删除已上传的相同属性的接口文档，保留最新上传的所述相同属性对应的接口文档；

其中，所述相同属性包括：相同的系统名称、相同的版本号和相同的接口地址。

10.如权利要求6至9任一项所述的接口文档的生成系统，其特征在于，所述接口文档的生成系统还包括：

索引模块，用于为已上传的所述接口文档建立索引；

搜索模块，用于接收到所述接口文档的搜索指令时，搜索已上传的所有接口文档，并将索引出的所述接口文档进行显示；

管理模块，用于对已索引的所述接口文档进行更新和维护。

Images