专利名称：自动生成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方法函数中，通常以O作为注解标识符；在方法 函数中记录的注解信息中往往包括有该方法函数的功能及参数信息；而利用Java的反射 机制生成的方法函数的反射对象中，往往包含了该方法函数的注解信息；因此，本发明的发 明人考虑到，可以利用反射对象中的注解信息自动生成该方法函数所涉及到的API接口的 描述文档，从而实现API接口的描述文档的自动生成，达到节约人力成本的目的；这样，在 API接口所涉及的方法函数被更新后，更便于根据更新后的方法函数及时重新生成该API 接口的描述文档，实现描述文档的及时更新。
下面结合附图详细说明本发明实施例的技术方案。基于上述思路，图1示出了针 对一个API接口，自动生成其描述文档的方法的流程图，具体包括如下步骤
SlOl :利用Java反射机制，针对API接口所涉及的方法函数，生成该方法函数的反 射对象。
事实上，方法函数是由程序人员编写的代码；一般而言，对于面向对象的编程方 式，多个方法函数可以属于一个类；编写完成的方法函数被映射为一个唯一的API接口供 第三方调用。第三方通过调用该API接口，可以实现与该API接口相映射的方法函数的功 能。本文中将与API接口具有映射关系的方法函数也称为该API接口所涉及的方法函数。
为了保证代码的可读性、具有较佳的可维护性，程序员编写的方法函数中除了代 码信息外，还会包括注解信息；这些注解信息以注解标识符标识；此外，遵循某些规范编写 的方法函数，其注解信息也遵循设定的规范。遵循设定规范的注解信息以注解标识符标识 出来,包括内容属性标签、注解内容；格式可以是注解标识符+内容属性标签+注解内 容；其中，内容属性标签后的注解内容对应该内容属性标签，该内容属性标签标识出其后对 应的注解内容的属性。
具体地，方法函数中的注解信息中，其内容属性标签可以包括
API接口描述属性标签其可以“OAPIDesc”进行标识，对应API接口描述属性标 签的注解内容包括API接口的功能描述；进一步，对应API接口描述属性标签的注解内容 还可包括API接口的授权方式、API接口的访问频次限制、返回的数据类型；进一步，对应 API接口描述属性标签的注解内容还可包括接口分类信息以及接口序号信息。例如，API 接口可以是按“关系图接口集”进行分类后，得到接口分类信息；或者API接口按“用户信息 接口集”进行分类后，得到接口分类信息；或者API接口按“时间线接口集”等进行分类后， 得到接口分类信息；接口序号信息用以表示该API接口在其所属接口分类中所排序号。
参数描述属性标签其可以“OParamDesc”进行标识，对应参数描述属性标签的注 解内容包括=API接口的参数描述；具体地，API接口的参数描述可以包括API接口的各参 数的数据类型、参数的取值范围、参数的默认值、参数的含义等。
请求方式属性标签其可以“OHttpMethod”进行标识,对应请求方式属性标签的 注解内容包括=API接口的请求方式的描述，即API接口的Http请求方式；例如，可以是GET 或POST请求方式。
此外，内容属性标签还可包括
路径属性标签其可以“ OPath ”进行标识，对应路径属性标签的注解内容包括路 径信息，用以指示该方法函数的路径。
接口数据格式属性标签其可以“OProduces”进行标识，对应接口数据格式属性 标签的注解内容包括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://ap1. weibo. com/2/users/show, ison
接口数据格式JSON ;
API接口的请求方式GET ；
API接口的参数(下表I所示)
表I
参*名是否必选类型及范围参数说_sourcefalsestring采用OAuth授权方式不需要此参数，其他授权方式为必填参数·数值为应用的AppKeyaccess一tokenfalsestring采用OAuth授权方式为必填参数，其他授权方式不需要此参数，OAuth授权后茯得uidfalseint64需要查询的用户IDscreennamefalsestring需要查询的用户昵称
在实际应用中，开放平台往往要提供数量众多的、一系列的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所示
表 权利要求
1.一种自动生成API接口的描述文档的方法，包括对于与所述API接口具有映射关系的方法函数，生成该方法函数的反射对象；获取所述反射对象中包含的该方法函数的注解信息；根据获取的注解信息，按预定格式生成所述API接口的描述文档。
2.如权利要求1所述的方法，其中，所述注解信息遵循设定规范并由注解标识符标识出来，所述注解信息包括内容属性标签,对应该内容属性标签的注解内容。
3.如权利要求2所述的方法，其中，所述内容属性标签包括API接口描述属性标签，对应该API接口描述属性标签的注解内容包括API接口的功能描述；参数描述属性标签，对应该参数描述属性标签的注解内容包括=API接口的参数描述；请求方式属性标签，对应该请求方式属性标签的注解内容包括API接口的请求方式的描述。
4.如权利要求3所述的方法，其中，所述根据获取的注解信息，按预定格式生成所述 API接口的描述文档具体包括在所述描述文档中，根据对应API接口描述属性标签的注解内容以预定格式记录API 接口的功能描述；根据对应参数描述属性标签的注解内容以预定格式记录API接口的参数描述；根据对应请求方式属性标签的注解内容以预定格式记录API接口的请求方式的描述。
5.如权利要求4所述的方法，其中，所述API接口为多个，以及与各API接口具有映射关系的方法函数在同一指定路径下，属于至少一个类；以及所述内容属性标签还包括路径属性标签；对应该路径属性标签的注解内容包括路径信息；以及，对应所述API接口描述属性标签的注解内容还包括接口分类信息以及接口序号信息。
6.如权利要求5所述的方法，其中，在所述按预定格式生成所述API接口的描述文档之前，还包括生成所述指定路径下的类的反射对象；对于生成的方法函数和类的反射对象，从中选择出具有路径属性标签的反射对象；针对每个选择出的反射对象，确定该反射对象中的注解信息中的接口分类信息以及接口序号信息；并根据确定出的接口分类信息以及接口序号信息对反射对象进行分类、排序后，以键-值形式存储到数据结构中；其中，所述键为接口分类信息，对应该键的值为具有该接口分类信息的反射对象；所述数据结构中，具有相同接口分类信息的反射对象依接口序号信息依次排列存储；在HTML格式的目录文件中对应各方法函数分别生成一个目录条目，目录条目的顺序依据上述数据结构中各反射对象的存储顺序；所述目录条目中记录了与其对应的方法函数具有映射关系的API接口的功能简介，以及该API接口的描述文档的超链接。
7.如权利要求6所述的方法，其中，所述根据获取的注解信息，按预定格式生成所述 API接口的描述文档还包括在所述API接口的描述文档中，根据第一注解信息中的对应该路径属性标签的注解内容和第二注解信息中的对应该路径属性标签的注解内容，以预定格式记录API接口的路径；其中，第一注解信息是从与该API接口具有映射关系的方法函数的反射对象中获取的， 第二注解信息是从该方法函数所属的类的反射对象中获取的。
8.一种自动生成API接口的描述文档的装置，其特征在于包括反射对象生成模块，用于对于与所述API接口具有映射关系的方法函数，生成该方法函数的反射对象；描述文档生成模块，用于获取所述反射对象生成模块生成的反射对象中包含的该方法函数的注解信息；根据获取的注解信息，按预定格式生成所述API接口的描述文档。
9.如权利要求8所述的装置，其特征在于，所述注解信息遵循设定规范并由注解标识符标识出来，所述注解信息包括内容属性标签,对应该内容属性标签的注解内容；其中，所述内容属性标签包括API接口描述属性标签，对应该API接口描述属性标签的注解内容包括API接口的功能描述；参数描述属性标签，对应该参数描述属性标签的注解内容包括=API接口的参数描述；请求方式属性标签，对应该请求方式属性标签的注解内容包括API接口的请求方式的描述。
10.如权利要求9所述的装置，其特征在于，所述API接口为多个，以及与各API接口具有映射关系的方法函数在同一指定路径下，属于至少一个类；以及所述内容属性标签还包括路径属性标签；对应该路径属性标签的注解内容包括路径信息；以及，对应所述API接口描述属性标签的注解内容还包括接口分类信息以及接口序号信息；以及所述反射对象生成模块还用于生成所述指定路径下的类的反射对象；以及所述装置还包括目录文件生成模块，用于对于所述反射对象生成模块生成的方法函数和类的反射对象，从中选择出具有路径属性标签的反射对象；针对每个选择出的反射对象，确定该反射对象中的注解信息中的接口分类信息以及接口序号信息；并根据确定出的接口分类信息以及接口序号信息对反射对象进行分类、排序后，以键-值形式存储到数据结构中；其中，所述键为接口分类信息，对应该键的值为具有该接口分类信息的反射对象；所述数据结构中，具有相同接口分类信息的反射对象依接口序号信息依次排列存储；在HTML格式的目录文件中对应各方法函数分别生成一个目录条目，目录条目的顺序依据上述数据结构中各反射对象的存储顺序；所述目录条目中记录了与其对应的方法函数具有映射关系的API接口的功能简介，以及该API接口的描述文档的超链接。
全文摘要
本发明公开了一种自动生成API接口的描述文档的方法和装置，所述方法包括对于与所述API接口具有映射关系的方法函数，生成该方法函数的反射对象；获取所述反射对象中包含的该方法函数的注解信息；根据获取的注解信息，按预定格式生成所述API接口的描述文档。由于利用反射机制生成方法函数的反射对象，并从反射对象中获取方法函数的注解信息，而注解信息中通常包括了该方法函数的功能的描述与参数的描述，因此，根据注解信息可自动生成预定格式的描述文档，从而实现自动生成涉及该方法函数的API接口的描述文档，节约人力成本，更便于描述文档与其API接口的更新的同步。
文档编号G06F9/44GK103049271SQ201210581818
公开日2013年4月17日 申请日期2012年12月27日 优先权日2012年12月27日
发明者张威 申请人:微梦创科网络科技(中国)有限公司