自动生成API接口的描述文档的方法和装置

摘要

本发明公开了一种自动生成API接口的描述文档的方法和装置，所述方法包括：对于与所述API接口具有映射关系的方法函数，生成该方法函数的反射对象；获取所述反射对象中包含的该方法函数的注解信息；根据获取的注解信息，按预定格式生成所述API接口的描述文档。由于利用反射机制生成方法函数的反射对象，并从反射对象中获取方法函数的注解信息，而注解信息中通常包括了该方法函数的功能的描述与参数的描述，因此，根据注解信息可自动生成预定格式的描述文档，从而实现自动生成涉及该方法函数的API接口的描述文档，节约人力成本，更便于描述文档与其API接口的更新的同步。

说明书

技术领域

本发明涉及计算机技术，尤其涉及自动生成API接口的描述文档的方法 和装置。

背景技术

当今众多的社交网站都提供一种开放的API（Application Program  Interface，应用程序接口）接口供第三方客户端或网站调用，达到信息快速分 享、增加用户粘度、开辟新的盈利模式的目的。这些网站提供的API接口中不 乏采用REST（Representational State Transfer，表述性状态转换）架构提供的 WEB（网络）服务解决方案。由于REST风格的WEB服务建立在HTTP（Hyper  Text Transport Protocol，超文本传输协议）协议之上，相比SOAP（Simple Object  Access Protocol，简单对象访问协议）以及XML-RPC等方案具有轻量、简单、 优雅、高效等特点，因而被众多社交网站的开放平台所青睐。例如，新浪微 博的开放平台目前就是建立在REST风格的WEB服务架构之上，对外开放了一 组功能完善的API接口。通过这些REST风格的API接口，第三方开发商可以开 发出和社交网站数据紧密整合的各种第三方应用，从而丰富用户的社交体验。 然而，随着API接口开放数量的增长以及API开放程度的加深，无论API接口的 调用方还是提供方的角度考虑，都需要对这些API接口进行规范化的文档描 述。

例如，从API接口的调用方角度来讲，由于提供的API接口数量众多，功 能各异，并且各API接口一直处于不断的更新和发展之中，如果没有一个准确 的、及时更新的描述文档系统，那么对于第三方的调用方而言，使用这些API 接口将是一件非常痛苦的事情。

然而，目前API接口的描述文档一般是由人工维护的，即由熟悉API接口 功能的程序员或相关技术人员在描述文档中记录该API接口的功能、参数等信 息；这使得API接口的描述文档的更新必须人工干预，需要付出额外的人力成 本来管理描述文档；更为严重的是，如果由于人员的疏忽，或其它原因造成 在API接口更新后没有及时更新其描述文档，则可能导致第三方的调用方错误 地使用API接口。因此，现有技术具有能够自动、及时更新API接口的描述文 档的需求。

发明内容

本发明的实施例提供了一种自动生成API接口的描述文档的方法和装置， 用以自动生成API接口的描述文档，节约人力成本，更便于描述文档与其API 接口的更新的同步。

根据本发明的一个方面，提供了一种自动生成API接口的描述文档的方 法，包括：

对于与所述API接口具有映射关系的方法函数，生成该方法函数的反射 对象；

获取所述反射对象中包含的该方法函数的注解信息；

根据获取的注解信息，按预定格式生成所述API接口的描述文档。

其中，所述注解信息遵循设定规范并由注解标识符标识出来，所述注解 信息包括：内容属性标签，对应该内容属性标签的注解内容。

所述内容属性标签包括：

API接口描述属性标签，对应该API接口描述属性标签的注解内容包括： API接口的功能描述；

参数描述属性标签，对应该参数描述属性标签的注解内容包括：API接口 的参数描述；

请求方式属性标签，对应该请求方式属性标签的注解内容包括：API接口 的请求方式的描述。

所述根据获取的注解信息，按预定格式生成所述API接口的描述文档具 体包括：

在所述描述文档中，根据对应API接口描述属性标签的注解内容以预定 格式记录API接口的功能描述；根据对应参数描述属性标签的注解内容以预 定格式记录API接口的参数描述；根据对应请求方式属性标签的注解内容以 预定格式记录API接口的请求方式的描述。

较佳地，所述API接口为多个，以及与各API接口具有映射关系的方法 函数在同一指定路径下，属于至少一个类；以及

所述内容属性标签还包括：路径属性标签；对应该路径属性标签的注解 内容包括：路径信息；以及，对应所述API接口描述属性标签的注解内容还 包括：接口分类信息以及接口序号信息。

较佳地，在所述按预定格式生成所述API接口的描述文档之前，还包括：

生成所述指定路径下的类的反射对象；

对于生成的方法函数和类的反射对象，从中选择出具有路径属性标签的 反射对象；

针对每个选择出的反射对象，确定该反射对象中的注解信息中的接口分 类信息以及接口序号信息；并根据确定出的接口分类信息以及接口序号信息 对反射对象进行分类、排序后，以键-值形式存储到数据结构中；其中，所述 键为接口分类信息，对应该键的值为具有该接口分类信息的反射对象；所述 数据结构中，具有相同接口分类信息的反射对象依接口序号信息依次排列存 储；

在HTML格式的目录文件中对应各方法函数分别生成一个目录条目，目 录条目的顺序依据上述数据结构中各反射对象的存储顺序；所述目录条目中 记录了与其对应的方法函数具有映射关系的API接口的功能简介，以及该API 接口的描述文档的超链接。

较佳地，所述根据获取的注解信息，按预定格式生成所述API接口的描 述文档还包括：

在所述API接口的描述文档中，根据第一注解信息中的对应该路径属性 标签的注解内容和第二注解信息中的对应该路径属性标签的注解内容，以预 定格式记录API接口的路径；其中，第一注解信息是从与该API接口具有映 射关系的方法函数的反射对象中获取的，第二注解信息是从该方法函数所属 的类的反射对象中获取的。

根据本发明的另一个方面，还提供了一种自动生成API接口的描述文档 的装置，包括：

反射对象生成模块，用于对于与所述API接口具有映射关系的方法函数， 生成该方法函数的反射对象；

描述文档生成模块，用于获取所述反射对象生成模块生成的反射对象中 包含的该方法函数的注解信息；根据获取的注解信息，按预定格式生成所述 API接口的描述文档。

其中，所述注解信息遵循设定规并息由注解标识符标识出来，所述注解 信息包括：内容属性标签，对应该内容属性标签的注解内容；

其中，所述内容属性标签包括：

API接口描述属性标签，对应该API接口描述属性标签的注解内容包括： API接口的功能描述；

参数描述属性标签，对应该参数描述属性标签的注解内容包括：API接口 的参数描述；

请求方式属性标签，对应该请求方式属性标签的注解内容包括：API接口 的请求方式的描述。

较佳地，所述API接口为多个，以及与各API接口具有映射关系的方法 函数在同一指定路径下，属于至少一个类；以及

所述内容属性标签还包括：路径属性标签；对应该路径属性标签的注解 内容包括：路径信息；以及，对应所述API接口描述属性标签的注解内容还 包括：接口分类信息以及接口序号信息；以及

所述反射对象生成模块还用于生成所述指定路径下的类的反射对象；以 及

所述装置还包括：

目录文件生成模块，用于对于所述反射对象生成模块生成的方法函数和 类的反射对象，从中选择出具有路径属性标签的反射对象；针对每个选择出 的反射对象，确定该反射对象中的注解信息中的接口分类信息以及接口序号 信息；并根据确定出的接口分类信息以及接口序号信息对反射对象进行分类、 排序后，以键-值形式存储到数据结构中；其中，所述键为接口分类信息，对 应该键的值为具有该接口分类信息的反射对象；所述数据结构中，具有相同 接口分类信息的反射对象依接口序号信息依次排列存储；在HTML格式的目 录文件中对应各方法函数分别生成一个目录条目，目录条目的顺序依据上述 数据结构中各反射对象的存储顺序；所述目录条目中记录了与其对应的方法 函数具有映射关系的API接口的功能简介，以及该API接口的描述文档的超 链接。

本发明实施例由于利用反射机制生成方法函数的反射对象，并从反射对 象中获取方法函数的注解信息，而注解信息中通常包括了该方法函数的功能 的描述与参数的描述；因此，根据注解信息可自动生成预定格式的描述文档； 从而实现自动生成涉及该方法函数的API接口的描述文档，节约人力成本， 更便于描述文档与其API接口的更新的同步。

附图说明

图1为本发明实施例的API接口的描述文档的自动生成方法流程图；

图2为本发明实施例的批量API接口的描述文档的自动生成方法流程图；

图3为本发明实施例的自动生成API接口的描述文档的装置的内部结构 框图。

具体实施方式

为使本发明的目的、技术方案及优点更加清楚明白，以下参照附图并举 出优选实施例，对本发明进一步详细说明。然而，需要说明的是，说明书中 列出的许多细节仅仅是为了使读者对本发明的一个或多个方面有一个透彻的 理解，即便没有这些特定的细节也可以实现本发明的这些方面。

本申请使用的“模块”、“系统”等术语旨在包括与计算机相关的实体， 例如但不限于硬件、固件、软硬件组合、软件或者执行中的软件。例如，模 块可以是，但并不仅限于：处理器上运行的进程、处理器、对象、可执行程 序、执行的线程、程序和/或计算机。举例来说，计算设备上运行的应用程序 和此计算设备都可以是模块。一个或多个模块可以位于执行中的一个进程和/ 或线程内，一个模块也可以位于一台计算机上和/或分布于两台或更多台计算 机之间。

本发明的发明人注意到，在API接口所涉及的方法函数（Method）中， 为了使方法函数中的代码具有较佳的可读性，程序员一般会在方法函数中增 加一些注解；这些注解以特定的注解标识符标识出来；例如，在Java方法函 数中，通常以作为注解标识符；在方法函数中记录的注解信息中往往包括 有该方法函数的功能及参数信息；而利用Java的反射机制生成的方法函数的 反射对象中，往往包含了该方法函数的注解信息；因此，本发明的发明人考 虑到，可以利用反射对象中的注解信息自动生成该方法函数所涉及到的API 接口的描述文档，从而实现API接口的描述文档的自动生成，达到节约人力 成本的目的；这样，在API接口所涉及的方法函数被更新后，更便于根据更 新后的方法函数及时重新生成该API接口的描述文档，实现描述文档的及时 更新。

下面结合附图详细说明本发明实施例的技术方案。基于上述思路，图1 示出了针对一个API接口，自动生成其描述文档的方法的流程图，具体包括 如下步骤：

S101：利用Java反射机制，针对API接口所涉及的方法函数，生成该方 法函数的反射对象。

事实上，方法函数是由程序人员编写的代码；一般而言，对于面向对象 的编程方式，多个方法函数可以属于一个类；编写完成的方法函数被映射为 一个唯一的API接口供第三方调用。第三方通过调用该API接口，可以实现 与该API接口相映射的方法函数的功能。本文中将与API接口具有映射关系 的方法函数也称为该API接口所涉及的方法函数。

为了保证代码的可读性、具有较佳的可维护性，程序员编写的方法函数 中除了代码信息外，还会包括注解信息；这些注解信息以注解标识符标识； 此外，遵循某些规范编写的方法函数，其注解信息也遵循设定的规范。遵循 设定规范的注解信息以注解标识符标识出来，包括：内容属性标签、注解内 容；格式可以是：注解标识符+内容属性标签+注解内容；其中，内容属性标 签后的注解内容对应该内容属性标签，该内容属性标签标识出其后对应的注 解内容的属性。

具体地，方法函数中的注解信息中，其内容属性标签可以包括：

API接口描述属性标签：其可以“APIDesc”进行标识，对应API接口 描述属性标签的注解内容包括：API接口的功能描述；进一步，对应API接 口描述属性标签的注解内容还可包括：API接口的授权方式、API接口的访问 频次限制、返回的数据类型；进一步，对应API接口描述属性标签的注解内 容还可包括：接口分类信息以及接口序号信息。例如，API接口可以是按“关 系图接口集”进行分类后，得到接口分类信息；或者API接口按“用户信息接 口集”进行分类后，得到接口分类信息；或者API接口按“时间线接口集” 等进行分类后，得到接口分类信息；接口序号信息用以表示该API接口在其 所属接口分类中所排序号。

参数描述属性标签：其可以“ParamDesc”进行标识，对应参数描述属 性标签的注解内容包括：API接口的参数描述；具体地，API接口的参数描述 可以包括API接口的各参数的数据类型、参数的取值范围、参数的默认值、 参数的含义等。

请求方式属性标签：其可以“HttpMethod”进行标识，对应请求方式属 性标签的注解内容包括：API接口的请求方式的描述，即API接口的Http请 求方式；例如，可以是GET或POST请求方式。

此外，内容属性标签还可包括：

路径属性标签：其可以“Path”进行标识，对应路径属性标签的注解内 容包括：路径信息，用以指示该方法函数的路径。

接口数据格式属性标签：其可以“Produces”进行标识，对应接口数据 格式属性标签的注解内容包括：API接口的数据格式信息，例如数据格式为 xml（Extensive Makeup Language，可扩展标示语言）或json（JavaScript Object  Notiation，基于Java Script语言的轻量级的数据交换格式）。

在本步骤中，可以利用Java反射机制，针对与API接口具有映射关系的 方法函数，生成该方法函数的反射对象。生成的反射对象中将包括有该方法 函数中记录的注解信息。

S102：从反射对象中获取注解信息。

S103：根据获取的注解信息，以预定格式生成该API接口的描述文档。

根据获取的注解信息，以预定格式生成的该API接口的描述文档中可以 包括：

根据对应API接口描述属性标签的注解内容以预定格式记录在描述文档 中的API接口的功能描述；进一步，还可在描述文档中记录API接口的授权 方式、API接口的访问频次限制、返回的数据类型等。

根据对应参数描述属性标签的注解内容以预定格式记录在描述文档中的 API接口的参数描述；

根据对应请求方式属性标签的注解内容以预定格式记录在描述文档中的 API接口的请求方式的描述。

进一步，描述文档中还可包括：

根据对应路径属性标签的注解内容记录的路径信息；

根据对应接口数据格式属性标签的注解内容记录的数据格式信息。

一个具体的描述文档可以如下所示，其中内容包括：

API接口的功能描述（users/show）：根据用户ID获取用户信息；

API接口的路径（URL）：https://api.weibo.com/2/users/show.json；

接口数据格式：JSON；

API接口的请求方式：GET；

API接口的参数：（下表1所示）

表1

在实际应用中，开放平台往往要提供数量众多的、一系列的API接口； 而程序员在更新某个API接口所涉及的方法函数时，也可能会对其它一些方 法函数进行改动；也就是说，在某次程序更新过程中，可能会涉及对多个API 接口的更新，因此，也就需要对多个API接口的描述文档进行更新；为了保 证被更新的API接口的描述文档全部被及时更新，一种较佳的方案是，对一 批相关的API接口，比如，对于属于同一项目下的API接口的描述文档同时 进行更新。

由此，本发明实施例还提供了针对一批API接口，自动生成描述文档的 方法函数，流程图如图2所示，包括如下步骤：

S201：对应指定路径下的类和方法函数，分别生成反射对象。

S202：根据生成的反射对象中的注解信息，选择出具有路径属性标签的 类和方法函数的反射对象。

S203：针对每个选择出的反射对象，确定其注解信息中的接口分类信息 以及接口序号信息。

S204：根据反射对象的接口分类信息以及接口序号信息，对选择出的反 射对象进行分类、排序后进行存储。

具体地，对选择出的反射对象进行分类、排序后，以键值key-value形式 存放在Linked Hash Map基于链表的有序哈希图数据结构中；其中，键key为 接口分类信息，对应该键的值value为具有该接口分类信息的反射对象；具有 相同接口分类信息的反射对象依接口序号信息依次排列存储于数据结构中。

S205：根据上述的数据结构，生成HTML格式的目录文件。

在本步骤中，在HTML（Hypertext Markup Language，超文本标记语言） 格式的目录文件中对应各方法函数分别生成一个目录条目，目录条目的顺序 依据上述数据结构中各反射对象的存储顺序；所述目录条目中记录了与其对 应的方法函数具有映射关系的API接口的功能简介，以及该API接口的描述 文档的超链接。这样，目录中记载的API接口是按照接口分类信息以及接口 序号信息排列的。即属同一接口分类的API接口在目录中排列在一起，并按 接口序号信息依次排列。

例如，一个具体的目录文件如下表2所示：

表2

S206：生成对应API接口的描述文档。

根据上述目录文件中记录的API接口的描述文档的超链接，在该超链接 指向处创建该API接口的描述文档；即该超链接指向存储的该API接口的描 述文档。

在创建的描述文档中，根据与该API接口具有映射关系的方法函数的反 射对象中的注解信息，生成该描述文档中的内容。根据与该API接口具有映 射关系的方法函数的反射对象中的注解信息，生成描述文档中的内容的具体 方法函数在上述图1所示的步骤中详细介绍了，此处不再赘述。较佳地，描 述文档中的API接口的路径信息是根据第一注解信息中的对应该路径属性标 签的注解内容和第二注解信息中的对应该路径属性标签的注解内容，以预定 格式记录的；其中，第一注解信息是从与该API接口具有映射关系的方法函 数的反射对象中获取的，第二注解信息是从该方法函数所属的类的反射对象 中获取的。

在实际应用中，上述的自动生成描述文档的方法函数可以应用在每次API 接口更新发布之前，针对API接口自动生成描述文档后，同时发布更新的API 接口及其描述文档。

本发明实施例提供的自动生成API接口的描述文档的装置，如图3所示， 包括：反射对象生成模块301、描述文档生成模块302。

反射对象生成模块301用于对于与所述API接口具有映射关系的方法函 数，生成该方法函数的反射对象；较佳地，所述API接口为多个，以及与各 API接口具有映射关系的方法函数在同一指定路径下，属于至少一个类；

描述文档生成模块302用于获取反射对象生成模块301生成的反射对象 中包含的该方法函数的注解信息；根据获取的注解信息，按预定格式生成所 述API接口的描述文档。

较佳地，所述注解信息遵循设定规范，以及所述注解信息由注解标识符 标识出来，包括：内容属性标签，对应该内容属性标签的注解内容；

其中，所述内容属性标签包括：

API接口描述属性标签，对应该API接口描述属性标签的注解内容包括： API接口的功能描述、接口分类信息以及接口序号信息；

参数描述属性标签，对应该参数描述属性标签的注解内容包括：API接口 的参数描述；

请求方式属性标签，对应该请求方式属性标签的注解内容包括：API接口 的请求方式的描述。

路径属性标签，对应该路径属性标签的注解内容包括：路径信息；

较佳地，上述的自动生成API接口的描述文档的装置还包括：目录文件 生成模块303。

上述的反射对象生成模块301还用于生成所述指定路径下的类的反射对 象。

目录文件生成模块303用于对于反射对象生成模块301生成的方法函数 和类的反射对象，从中选择出具有路径属性标签的反射对象；针对每个选择 出的反射对象，确定该反射对象中的注解信息中的接口分类信息以及接口序 号信息；并根据确定出的接口分类信息以及接口序号信息对反射对象进行分 类、排序后，以键-值形式存储到数据结构中；其中，所述键为接口分类信息， 对应该键的值为具有该接口分类信息的反射对象；所述数据结构中，具有相 同接口分类信息的反射对象依接口序号信息依次排列存储；生成HTML格式 的目录文件，在HTML格式的目录文件中对应各方法函数分别生成一个目录 条目，目录条目的顺序依据上述数据结构中各反射对象的存储顺序；所述目 录条目中记录了与其对应的方法函数具有映射关系的API接口的功能简介， 以及该API接口的描述文档的超链接，该超链接指向由描述文档生成模块302 生成的该API接口的描述文档的存储地址。目录文件生成模块303输出生成 的目录文件。

在实际应用中，上述的自动生成API接口的描述文档的装置可以应用在 API接口发布工具中，在每次API接口更新发布之前，针对API接口自动生 成描述文档后，同时发布更新的API接口及其描述文档。

本发明实施例由于利用反射机制生成方法函数的反射对象，并从反射对 象中获取方法函数的注解信息，而注解信息中通常包括了该方法函数的功能 的描述与参数的描述；因此，根据注解信息可自动生成预定格式的描述文档； 从而实现自动生成涉及该方法函数的API接口的描述文档，节约人力成本， 更便于描述文档与其API接口的更新的同步。

本领域普通技术人员可以理解实现上述实施例方法中的全部或部分步骤 是可以通过程序来指令相关的硬件来完成，该程序可以存储于一计算机可读 取存储介质中，如：ROM/RAM、磁碟、光盘等。

以上所述仅是本发明的优选实施方式，应当指出，对于本技术领域的普 通技术人员来说，在不脱离本发明原理的前提下，还可以作出若干改进和润 饰，这些改进和润饰也应视为本发明的保护范围。