[发明专利]自动生成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接口的描述文档之前，还包括：

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

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