CN107193570A - 一种自动生成api文档的方法及系统 - Google Patents

Abstract

本申请公开了一种自动生成API文档的方法，包括：对原始后台代码执行附加apidoc注释的处理，得到附加apidoc注释的后台代码；对后台代码利用apidoc工具生成对应的API文档；当后台代码被修改时，相应的修改所述apidoc注释，得到最新版后台代码；将最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。能够以更加合理、更加及时的生成API文档的方法来消除因重复修改出现的遗漏生成最新版API文档的潜在隐患、提升后台与前端工程师之间的工作效率。本申请还公开了一种自动生成API文档的系统，具有上述有益效果。

Description

一种自动生成API文档的方法及系统

技术领域

本申请涉及WEB应用开发技术领域，特别涉及一种自动生成API文档的方法及系统。

背景技术

随着时代的发展，人们更多地使用智能移动终端上安装的各种应用程序(APP)获取各种信息，其中很多APP都会有自己的云服务后台，或用来由APP自身自动获取新的信息并实时更新，或是由后台开发人员进行信息的更新或在线不停机的修复一些小的Bug。

当前，作为做部分APP和云服务后台之间的标准连接方式，REST API(REST即表述性状态传递，英文全称：Representational State Transfer，是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性的一种软件架构风格；API即应用程序编程接口，英文全称：Application Programming Interface)已经得到了绝大部分APP开发者的认可并已经开始广泛的应用，尤其是在近些年中，随着新型API经济模式的逐渐兴起，许多开发者厂商纷纷将自己的后台业务能力作为REST API开放出来，给更广泛的第三方开发者使用。

但是，在进行开发一个大型APP时，不可避免的会致使开发团队异常庞大，往往会出现后台工程师所编写的代码无法被前端工程师理解清楚，而两者之间的交流是一个非常费时费力的过程，再加上若开发需求变动、沟通不及时等情况出现，很容易出现后台工程师发布的APP版本与前端工程师看到的版本不一致的问题。

在现行的管理方法中，主要通过后端工程师为代码段书写注释并一次次通过apidoc工具(一种提取apidoc注释格式并生成API文档的软件)生成相应的API文档将其发送给前端工程师，随着修改次数的增多，也依然会出现上述问题，那么，如何在无法避免需要重复生成最新版API文档的前提下，提供一种更合理、更及时、不遗漏的以及非手动生成的自动生成最新版API文档机制，是本领域技术人员亟待解决的问题。

发明内容

本申请的目的是提供一种自动生成API文档的方法及系统，能够以一个更加合理、更及时的方法来消除因重复修改出现的遗漏生成最新版API文档的潜在隐患、提升后台与前端工程师之间的工作效率。

为解决上述技术问题，本申请提供一种自动生成API文档的方法，该方法包括：

对原始后台代码执行附加apidoc注释的处理，得到附加所述apidoc注释的后台代码；其中，所述apidoc注释为按照apidoc的注释标签格式书写的；

对所述后台代码利用apidoc工具生成对应的API文档；

当所述后台代码被修改时，相应的修改所述apidoc注释，得到最新版后台代码；

将所述最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。

可选的，将所述最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档，包括：

当所述最新版后台代码合并进git库时，触发shell脚本调用所述apidoc工具；

通过所述apidoc工具生成所述最新版API文档至指定的服务器路径下；

所述shell脚本将所述最新版API文档从所述服务器路径下复制到用户阅读路径下。

可选的，利用所述apidoc工具生成所述最新版API文档至指定的服务器路径下，包括：

利用所述apidoc工具生成静态且为html格式的所述最新版API文档至指定的服务器路径下。

可选的，在为原始后台代码进行添加apidoc注释的处理前，还包括：

在git库的服务器上安装node.js环境，并在联网情况下安装所述apidoc工具。

本申请还提供了一种生成API文档的系统，该系统包括：

添加注释单元，用于对原始后台代码执行附加apidoc注释的处理，得到附加所述apidoc注释的后台代码；其中，所述apidoc注释为按照apidoc的注释标签格式书写的；

第一生成单元，用于对所述后台代码利用apidoc工具生成对应的API文档；

修改单元，用于当所述后台代码被修改时，相应的修改所述apidoc注释，得到最新版后台代码；

第二生成单元，用于将所述最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。

可选的，所述第二生成单元包括：

脚本触发子单元，用于当所述最新版后台代码合并进git库时，触发shell脚本调用所述apidoc工具；

生成子单元，用于通过所述apidoc工具生成所述最新版API文档至指定的服务器路径下；

复制转移子单元，用于所述shell脚本将所述最新版API文档从所述服务器路径下复制到用户阅读路径下。

可选的，所述生成子单元具体为：

利用所述apidoc工具生成静态且为html格式的所述最新版API文档至指定的服务器路径下的子单元。

可选的，还包括：

环境安装单元，用于在git库的服务器上安装node.js环境，并在联网情况下安装所述apidoc工具。

本申请所提供的自动生成API文档的方法，通过对原始后台代码执行附加apidoc注释的处理，得到附加所述apidoc注释的后台代码；其中，所述apidoc注释为按照apidoc的注释标签格式书写的；对所述后台代码利用apidoc工具生成对应的API文档；当所述后台代码被修改时，相应的修改所述apidoc注释，得到最新版后台代码；将所述最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。

显然，本申请所提供的技术方案通过自动将后台工程师修改后的最新版后台代码及时生成最新版API文档，以使前端工程师能够及时且不遗漏的得到最新的API文档。因此，能够以更加合理、更加及时的生成API文档的方法来消除因重复修改出现的遗漏生成最新版API文档的潜在隐患、提升后台与前端工程师之间的工作效率。本申请同时还提供了一种自动生成API文档的系统，具有上述有益效果，在此不再赘述。

附图说明

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

图1为本申请实施例所提供的一种自动生成API文档的方法的流程图；

图2为本申请实施例所提供的另一种自动生成API文档的方法的流程图；

图3为本申请实施例所提供的又一种自动生成API文档的方法的流程图；

图4为本申请实施例所提供的一种自动生成API文档的方法系统的结构图。

具体实施方式

本申请的核心是提供一种自动生成API文档的方法及系统，能够以一个更加合理、更及时的方法来消除因重复修改出现的遗漏生成最新版API文档的潜在隐患、提升后台与前端工程师之间的工作效率。

为使本申请实施例的目的、技术方案和优点更加清楚，下面将结合本申请实施例中的附图，对本申请实施例中的技术方案进行清楚、完整地描述，显然，所描述的实施例是本申请一部分实施例，而不是全部的实施例。基于本申请中的实施例，本领域普通技术人员在没有做出创造性劳动前提下所获得的所有其他实施例，都属于本申请保护的范围。

以下结合图1，图1为本申请实施例所提供的一种自动生成API文档的方法的流程图。

其具体包括以下步骤：

S101：对原始后台代码执行附加apidoc注释的处理，得到附加apidoc注释的后台代码；

本步骤的目的在于为原始的后台代码附加按照apidoc注释标签格式书写的apidoc注释，得到该附加apidoc注释的后台代码。

其中，该apidoc注释包括一些代码段的必要信息，例如，api说明、参数说明、请求方式、请求示例以及返回示例等等。通过将这些代码段所要表达的必要信息以注释的形式书写进原始后台代码，以使得到的附加该apidoc注释的后台代码更便于被前端工程师所理解。

S102：对后台代码利用apidoc工具生成对应的API文档；

将经过S101得到的附加该apidoc注释的后台代码通过apidoc工具生成对应的API文档。其中，该apidoc工具是一个自动提取书写进代码段中的符合apidoc注释格式的apidoc注释的工具，且该apidoc注释支持多种开发语言环境，例如，java、Javascript、php、python、ruby、go等。该apidoc工具将注释提取出来后会生成一个静态的以HTML格式存在的API文档。静态的HTML格式API文档文件具有在访问该文件时无需再次联网，是一个已经保存在本地的完整的文件，并非是一个网页链接，所以在发生紧急情况下或没有联网的情况下依然可以访问。

S103：是否修改了后台代码；

本步骤是判断是否发生了需要对S102使用的附加了apidoc注释的后台代码进行修改，而会导致发生需要对代码段进行修改的因素多种多样，例如，APP功能性的修改、发布平台的各种要求以及修复各种小Bug等等因素，此处并不限定是出于什么样的因素需要进行对后台代码的修改，只要满足对代码段进行了修改这一结果即可。

S104：相应的修改apidoc注释，得到最新版后台代码；

一旦在S103出于各种因素对后台代码进行了修改，相应的肯定要修改原来附加上的apidoc注释，并书写得到符合修改后的后台代码所对应的新版apidoc注释，最终得到附加了新版apidoc注释的最新版后台代码。

S105：将最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。

在得到S104中的最新版后台代码后，后台工程师会将该最新版后台代码合进需要的代码库，此处的git库是一种代码管理库，当合进该git库后，该git库的服务器会根据预设脚本调用执行一系列预设命令来生成最新版API文档，得以及时、无遗漏的生成最新版API文档。

其中预设脚本以及预设命令的表现形式多种多样，此处并不限定具体为什么样的脚本、什么样的命令，只要该预设脚本以及预设命令能够最终实现自动根据最新版后台代码来生成最新版API文档即可，在实际情况中，可以根据开发厂商的不同、采用服务器型号的不同、操作习惯的不同等各种因素来综合考虑作出相应的差异化改变。

基于上述技术方案，本申请实施例提供的自动生成API文档的方法，通过自动将后台工程师修改后的最新版后台代码及时生成最新版API文档，以使前端工程师能够及时且不遗漏的得到最新的API文档。因此，能够以更加合理、更加及时的生成API文档的方法来消除因重复修改出现的遗漏生成最新版API文档的潜在隐患、提升后台与前端工程师之间的工作效率。

下面请参见图2，图2为本申请实施例所提供的另一种自动生成API文档的方法的流程图。

本实施是针对上一实施例中的S105做出了具体的限定，其他步骤与上一实施例大体相同，详细描写内容可以参见上一实施例中相关部分，在此不再赘述。

其具体包括以下步骤：

S201：当最新版后台代码合并进git库时，触发shell脚本调用apidoc工具；

本步骤通过在该最新版后台代码合进该git库时，触发该git库服务器的shell脚本，通过该shell脚本调用执行内置在该git库服务器中的apidoc工具。

S202：通过apidoc工具生成最新版API文档至指定的服务器路径下；

通过S201步骤调用的该apidoc工具来将该最新版后台代码中书写的新版apidoc注释提取出来并生成静态的以HTML格式存在的最新版API文档，并将该API文档置于指定的服务器路径下。其中，将该该API文档置于指定的服务器路径下是出于多方面因素的考量，该服务器一定是该APP开发商所拥有的，不管出于安全性因素的考虑还是传输方便的考虑，是至少需要在该服务器中存有相应的备份文件的。

S203：shell脚本将最新版API文档从服务器路径下复制到用户阅读路径下。

该shell脚本将从S202得到的且置于指定服务器路径下的该最新版API文档再次从指定服务器路径下复制至前端工程师以及后台工程师常用的文件路径下，以便在服务器端进行过备份后，也便于前端以及后台工程师的查看。

下面请参见图3，图3为本申请实施例所提供的又一种自动生成API文档的方法的流程图。

本实施例建立在一个具体的实际的应用场景中，选择了一个APP开发商的实例，以及指令了生成的保存API文档的服务器以及供工程进行阅读的文档路径。

其具体包括以下步骤：

S301：在git库的服务器上安装node.js环境，并在联网情况下安装apidoc工具；

在后续所有步骤开始之前，需要保证在该git库的服务器上安装能够运行该apidoc工具的环境，即，首先安装node.js环境，接下来只需在联网情况下安装apidoc工具即可。

S302:对原始后台代码执行附加apidoc注释的处理，得到附加apidoc注释的后台代码；

S303：对后台代码利用apidoc工具生成对应的API文档；

S304：对后台代码进行修改，相应的修改apidoc注释，得到最新版后台代码；

S305：当最新版后台代码合并进git库时，触发shell脚本调用apidoc工具；

S306：生成最新版API文档至公司1#开发服务器；

指定备份该最新版API文档的为该开发厂商的1#git库开发服务器。

S307：shell脚本将最新版API文档从1#开发服务器复制到1#共享文件夹。

指定便于前端以及后台工程师便于查看的路径为1#共享文件夹。

基于上述技术方案，本申请实施例提供的自动生成API文档的方法，通过在将后台工程师修改后的最新版后台代码合进该git库时，调用shell脚本执行一系列指令并最终得到置于便于前端以及后台工程师便于查看的路径下的最新版API文档，以使前端工程师能够及时且不遗漏的得到最新的API文档。因此，能够以更加合理、更加及时的生成API文档的方法来消除因重复修改出现的遗漏生成最新版API文档的潜在隐患、提升后台与前端工程师之间的工作效率。

上面提及的几种方式，只是从实际出发提出的几种具体例子，当然可以有其他的方式来达到同样的效果，此处并不做具体限定。

下面请参见图4，图4为本申请实施例所提供的一种自动生成API文档的系统的结构图。

该系统可以包括：

添加注释单元，用于对原始后台代码执行附加apidoc注释的处理，得到附加apidoc注释的后台代码；其中，apidoc注释为按照apidoc的注释标签格式书写的；

第一生成单元，用于对后台代码利用apidoc工具生成对应的API文档；

修改单元，用于当后台代码被修改时，相应的修改apidoc注释，得到最新版后台代码；

第二生成单元，用于将最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。

进一步的，第二生成单元，包括：

脚本触发子单元，用于当最新版后台代码合并进git库时，触发shell脚本调用apidoc工具；

生成子单元，用于通过apidoc工具生成最新版API文档至指定的服务器路径下；

复制转移子单元，用于shell脚本将最新版API文档从服务器路径下复制到用户阅读路径下。

其中，生成子单元具体为：

利用apidoc工具生成静态且为html格式的最新版API文档至指定的服务器路径下的子单元。

进一步，该系统还包括：

环境安装单元，用于在git库的服务器上安装node.js环境，并在联网情况下安装apidoc工具。

下面为在添加注释单元中进行一个实际的书写例子，以java开发环境为例：

之后在第二生成单元中的生成子单元中使用命令apidoc–i–t–o，指定相应的目录即可生成相应的最新版API文档。

说明书中各个实施例采用递进的方式描述，每个实施例重点说明的都是与其他实施例的不同之处，各个实施例之间相同相似部分互相参见即可。对于实施例公开的装置而言，由于其与实施例公开的方法相对应，所以描述的比较简单，相关之处参见方法部分说明即可。

专业人员还可以进一步意识到，结合本文中所公开的实施例描述的各示例的单元及算法步骤，能够以电子硬件、计算机软件或者二者的结合来实现，为了清楚地说明硬件和软件的可互换性，在上述说明中已经按照功能一般性地描述了各示例的组成及步骤。这些功能究竟以硬件还是软件方式来执行，取决于技术方案的特定应用和设计约束条件。专业技术人员可以对每个特定的应用来使用不同方法来实现所描述的功能，但是这种实现不应认为超出本申请的范围。

以上对本申请所提供的自动生成API文档的方法及系统进行了详细介绍。本文中应用了具体个例对本申请的原理及实施方式进行了阐述，以上实施例的说明只是用于帮助理解本申请的方法及其核心思想。应当指出，对于本技术领域的普通技术人员来说，在不脱离本申请原理的前提下，还可以对本申请进行若干改进和修饰，这些改进和修饰也落入本申请权利要求的保护范围内。

还需要说明的是，在本说明书中，诸如第一和第二等之类的关系术语仅仅用来将一个实体或者操作与另一个实体或操作区分开来，而不一定要求或者暗示这些实体或操作之间存在任何这种实际的关系或者顺序。而且，术语“包括”、“包含”或者其任何其他变体意在涵盖非排他性的包含，从而使得包括一系列要素的过程、方法、物品或者设备不仅包括那些要素，而且还包括没有明确列出的其他要素，或者是还包括为这种过程、方法、物品或者设备所固有的要素。在没有更多限制的情况下，由语句“包括一个……”限定的要素，并不排除在包括所述要素的过程、方法、物品或者设备中还存在另外的相同要素。

Claims (8)

1.一种自动生成API文档的方法，其特征在于，包括：

对原始后台代码执行附加apidoc注释的处理，得到附加所述apidoc注释的后台代码；其中，所述apidoc注释为按照apidoc的注释标签格式书写的；

对所述后台代码利用apidoc工具生成对应的API文档；

当所述后台代码被修改时，相应的修改所述apidoc注释，得到最新版后台代码；

将所述最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。

2.根据权利要求1所述的方法，其特征在于，将所述最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档，包括：

将所述最新版后台代码合并进git库后，触发shell脚本调用所述apidoc工具；

通过所述apidoc工具生成所述最新版API文档至指定的服务器路径下；

所述shell脚本将所述最新版API文档从所述服务器路径下复制到用户阅读路径下。

3.根据权利要求2所述的方法，其特征在于，利用所述apidoc工具生成所述最新版API文档至指定的服务器路径下，包括：

利用所述apidoc工具生成静态且为html格式的所述最新版API文档至指定的服务器路径下。

4.根据权利要求1至3任一项所述的方法，其特征在于，在为原始后台代码进行添加apidoc注释的处理前，还包括：

在git库的服务器上安装node.js环境，并在联网情况下安装所述apidoc工具。

5.一种生成API文档的系统，其特征在于，包括：

添加注释单元，用于对原始后台代码执行附加apidoc注释的处理，得到附加所述apidoc注释的后台代码；其中，所述apidoc注释为按照apidoc的注释标签格式书写的；

第一生成单元，用于对所述后台代码利用apidoc工具生成对应的API文档；

修改单元，用于当所述后台代码被修改时，相应的修改所述apidoc注释，得到最新版后台代码；

第二生成单元，用于将所述最新版后台代码合并进git库，并根据预设脚本调用预设命令生成最新版API文档。

6.根据权利要求5所述的系统，其特征在于，所述第二生成单元包括：

脚本触发子单元，用于当所述最新版后台代码合并进git库时，触发shell脚本调用所述apidoc工具；

生成子单元，用于通过所述apidoc工具生成所述最新版API文档至指定的服务器路径下；

复制转移子单元，用于所述shell脚本将所述最新版API文档从所述服务器路径下复制到用户阅读路径下。

7.根据权利要求6所述的系统，其特征在于，所述生成子单元具体为：

利用所述apidoc工具生成静态且为html格式的所述最新版API文档至指定的服务器路径下的子单元。

8.根据权利要求5至7任一项所述的系统，其特征在于，还包括：

环境安装单元，用于在git库的服务器上安装node.js环境，并在联网情况下安装所述apidoc工具。