CN110825430A - 一种api文档生成方法、装置、设备及存储介质 - Google Patents

Abstract

本发明公开了一种API文档生成方法、装置、设备及存储介质。该方法的步骤包括：获取API源代码，并将API源代码加载至IDEA集成开发环境；调用IDEA集成开发环境的PSI程序结构接口对API源代码进行解析以生成对象树；提取对象树中各函数类的元数据，元数据为描述函数类的属性的数据；根据元数据生成API文档。本方法通过利用IDEA集成开发环境中的PSI程序结构接口对API源代码中各函数类的元数据进行提取，并以此生成API文档，相对降低了产生API文档过程所需的人工成本，并保证了所生成的API文档的准确性。此外，本发明还提供一种API文档生成装置、设备及存储介质，有益效果同上所述。

Description

一种API文档生成方法、装置、设备及存储介质

技术领域

本发明涉及软件开发领域，特别是涉及一种API文档生成方法、装置、设备及存储介质。

背景技术

目前的软件项目日趋复杂，一个软件系统通常由若干个子系统组成形式上的统一体，共同对外提供服务。软件系统在运行过程中，其各个子系统之间的通信不可避免，通信意味着双方需要遵循统一的网络协议，比如RPC或HTTP。

由于前端的客户端和后端的服务端一般由不同的开发人员开发，因此服务端需要通过开发人员定义的API(Application Programming Interface，即应用程序编程接口)对外提供服务，客户端则需要根据API提供的功能进行对接开发，因此用于描述服务端API功能的API文档必不可少，但是当前的API文档往往需要开发人员根据API的结构进行单独的编写，因此会产生一定的人工成本，并且开发人员对于API文档的主观编写也难以确保API文档的准确性。

由此可见，提供一种API文档生成方法，以相对降低产生API文档过程所需的人工成本，并保证所生成的API文档的准确性，是本领域技术人员需要解决的问题。

发明内容

本发明的目的是提供一种API文档生成方法、装置、设备及存储介质，以相对降低产生API文档过程所需的人工成本，并保证所生成的API文档的准确性。

为解决上述技术问题，本发明提供一种API文档生成方法，包括：

获取API源代码，并将API源代码加载至IDEA集成开发环境；

调用IDEA集成开发环境的PSI程序结构接口对API源代码进行解析以生成对象树；

提取对象树中各函数类的元数据，元数据为描述函数类的属性的数据；

根据元数据生成API文档。

优选地，在根据元数据生成API文档之前，方法还包括：

获取由用户设置的系统路径；

在根据元数据生成API文档之后，方法还包括：

将API文档存储至系统路径。

优选地，元数据包括注释、类名、方法名、输入参数以及返回参数。

优选地，当API源代码的语言类型为Java类型时，元数据还包括Javadoc。

优选地，在根据元数据生成API文档之前，方法还包括：

获取对象树中各函数类之间的结构关系；

根据元数据生成API文档，包括：

依照结构关系对各函数类的元数据进行组合以生成API文档。

此外，本发明还提供一种API文档生成装置，包括：

源代码加载模块，用于获取API源代码，并将API源代码加载至IDEA集成开发环境；

接口调用模块，用于调用IDEA集成开发环境的PSI程序结构接口对API源代码进行解析以生成对象树；

元数据提取模块，用于提取对象树中各函数类的元数据，元数据为描述函数类的属性的数据；

文档生成模块，用于根据元数据生成API文档。

优选地，装置还包括：

路径获取模块，用于获取由用户设置的系统路径；

路径存储模块，用于将API文档存储至系统路径。

优选地，装置还包括：

关系获取模块，用于获取对象树中各函数类之间的结构关系；

文档生成模块，包括：

嵌套生成模块，用于依照结构关系对各函数类的元数据进行组合以生成API文档。

此外，本发明还提供一种API文档生成设备，包括：

存储器，用于存储计算机程序；

处理器，用于执行计算机程序时实现如上述的API文档生成方法的步骤。

此外，本发明还提供一种计算机可读存储介质，计算机可读存储介质上存储有计算机程序，计算机程序被处理器执行时实现如上述的API文档生成方法的步骤。

本发明所提供的API文档生成方法，首先获取API源代码，将源代码加载至IDEA集成开发环境中，并调用该IDEA集成开发环境的PSI程序结构接口对API源代码进行解析并生成对象树，进而提取对象树中各函数类中能够描述函数类的属性的元数据，并根据元数据生成API文档。本方法通过利用IDEA集成开发环境中的PSI程序结构接口对API源代码中各函数类的元数据进行提取，并以此生成API文档，进而无需以人工方式编写API文档，相对降低了产生API文档过程所需的人工成本，并保证了所生成的API文档的准确性。此外，本发明还提供一种API文档生成装置、设备及存储介质，有益效果同上所述。

附图说明

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

图1为本发明实施例公开的一种API文档生成方法的流程图；

图2为本发明实施例公开的一种API文档生成装置的结构示意图。

具体实施方式

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

由于前端的客户端和后端的服务端一般由不同的开发人员开发，因此服务端需要通过开发人员定义的API(Application Programming Interface，即应用程序编程接口)对外提供服务，客户端则需要根据API提供的功能进行对接开发，因此用于描述服务端API功能的API文档必不可少，但是当前的API文档往往需要开发人员根据API的结构进行单独的编写，因此会产生一定的人工成本，并且开发人员对于API文档的主观编写也难以确保API文档的准确性。

为此，本发明的核心是提供一种API文档生成方法，以相对降低产生API文档过程所需的人工成本，并保证所生成的API文档的准确性。

为了使本技术领域的人员更好地理解本申请方案，下面结合附图和具体实施方式对本发明作进一步的详细说明。

参见图1所示，本发明实施例公开了一种API文档生成方法，包括：

步骤S10：获取API源代码，并将API源代码加载至IDEA集成开发环境。

本步骤首先获取API源代码，该API源代码即为与本实施例中所生成的API文档对应的源代码，进而在获取到API源代码后，进一步将API源代码加载至IDEA集成开发环境，将API源代码加载至IDEA集成开发环境的目的是确保IDEA集成开发环境能够对API源代码进行后续的解析操作。另外，IDEA的全称为IntelliJ IDEA，是包括java编程语言在内的程序的开发集成环境。

步骤S11：调用IDEA集成开发环境的PSI程序结构接口对API源代码进行解析以生成对象树。

在将API源代码加载至IDEA集成开发环境后，本步骤进一步调用IDEA集成开发环境的PSI程序结构接口对API源代码进行解析以生成对象树，其中，IDEA集成开发环境的PSI程序结构接口，即PSI(Program Structure Interface)，是Intellij Platform提供的一套用于开发IDEA插件的标准接口，在IDEA集成开发环境所管理的开发工程中，每个目录、包、源代码和资源文件都会被抽象成相应的PSI对象。在本步骤中，调用IDEA集成开发环境的PSI程序结构接口对API源代码进行解析并生成的对象树，即为IDEA集成开发环境对API源代码进行抽象提取得到的PSI对象。对象树记录的是API源代码中函数类之间的结构关系，也就是API源代码中各个函数类之间的引用、嵌套关系。

步骤S12：提取对象树中各函数类的元数据，元数据为描述函数类的属性的数据。

本步骤基于对象树进一步检索API源代码中的各个函数类中包含的元数据，元数据指的是能够表征函数类的属性的数据，也就是函数类的固有特征。

步骤S13：根据元数据生成API文档。

由于元数据记录的是函数类的固有特征，因此本步骤进一步根据元数据生成API文档，进而用户能够根据API文档获悉API源代码中函数类的属性。

本发明所提供的API文档生成方法，首先获取API源代码，将源代码加载至IDEA集成开发环境中，并调用该IDEA集成开发环境的PSI程序结构接口对API源代码进行解析并生成对象树，进而提取对象树中各函数类中能够描述函数类的属性的元数据，并根据元数据生成API文档。本方法通过利用IDEA集成开发环境中的PSI程序结构接口对API源代码中各函数类的元数据进行提取，并以此生成API文档，进而无需以人工方式编写API文档，相对降低了产生API文档过程所需的人工成本，并保证了所生成的API文档的准确性。

在上述实施例的基础上，本发明还提供以下一系列优选的实施方式。

作为一种优选的实施方式，在根据元数据生成API文档之前，方法还包括：

获取由用户设置的系统路径；

在根据元数据生成API文档之后，方法还包括：

将API文档存储至系统路径。

需要说明的是，在本实施方式中，预先获取用户设置的系统路径，进而在根据元数据生成API文档后，将该API文档存储至用户设置的系统路径中，进而用户能够在自身规定的系统路径下获取到基于API源代码生成的API文档，确保了用户能够便捷获取到生成的API文档，确保了用户对于API文档的高效使用。

作为一种优选的实施方式，元数据包括注释、类名、方法名、输入参数以及返回参数。

其中，注释指的是开发人员在对API源代码进行编写时，对于类函数以及类函数中的字段内容的解释性说明；类名指的是类函数的名称，即确保类函数唯一性的标识；方法名指的是类函数中进一步包含的函数方法的名称，即表征类函数所具有的功能；输入参数以及返回参数分别指的是函数方法执行时所需要的参数以及函数方法执行后产生的结果。本实施方式能够相对确保API文档内容的全面性。

更进一步的，作为一种优选的实施方式，当API源代码的语言类型为Java类型时，元数据还包括Javadoc。

需要说明的是，Javadoc是Java编程语言提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。也就是说，只要在编写程序时以一套特定的标签作注释，在程序编写完成后，通过Javadoc就可以同时形成程序的开发文档了，因此Javadoc可以理解为是对源代码中的类函数、方法、成员等属性进行的初步抽象，因此基于包含有Javadoc的元数据生成API文档，能够进一步确保API文档内容的丰富性以及准确性。

在上述一系列实施方式的基础上，作为一种优选的实施方式，在根据元数据生成API文档之前，方法还包括：

获取对象树中各函数类之间的结构关系；

根据元数据生成API文档，包括：

依照结构关系对各函数类的元数据进行组合以生成API文档。

需要说明的是，本实施方式的重点是在根据元数据生成API文档之前，预先获取对象树中各个函数类之间的结构关系，进而依照该结构关系对各个函数类中提取的元数据进行组合，生成相应的API文档。由于API源代码中的各个函数类之间存在一定的嵌套关系，即本实施方式中的结构关系，而元数据是在函数类中提取得到的，因此在不同函数类中获取到的元数据之间也符合函数类之间的结构关系，进而本实施方式依照结构关系对各函数类的元数据进行组合以生成API文档，以此相对确保了API文档内容的可读性。

参见图2所示，本发明实施例公开了一种API文档生成装置，包括：

源代码加载模块10，用于获取API源代码，并将API源代码加载至IDEA集成开发环境。

接口调用模块11，用于调用IDEA集成开发环境的PSI程序结构接口对API源代码进行解析以生成对象树。

元数据提取模块12，用于提取对象树中各函数类的元数据，元数据为描述函数类的属性的数据。

文档生成模块13，用于根据元数据生成API文档。

本发明所提供的API文档生成装置，首先获取API源代码，将源代码加载至IDEA集成开发环境中，并调用该IDEA集成开发环境的PSI程序结构接口对API源代码进行解析并生成对象树，进而提取对象树中各函数类中能够描述函数类的属性的元数据，并根据元数据生成API文档。本装置通过利用IDEA集成开发环境中的PSI程序结构接口对API源代码中各函数类的元数据进行提取，并以此生成API文档，进而无需以人工方式编写API文档，相对降低了产生API文档过程所需的人工成本，并保证了所生成的API文档的准确性。

此外，在上述API文档生成装置的基础上，本发明还提供如下的优选技术方案。

作为一种优选的实施方式，装置还包括：

路径获取模块，用于获取由用户设置的系统路径；

路径存储模块，用于将API文档存储至系统路径。

另外，作为一种优选的实施方式，装置还包括：

关系获取模块，用于获取对象树中各函数类之间的结构关系；

文档生成模块，包括：

嵌套生成模块，用于依照结构关系对各函数类的元数据进行组合以生成API文档。

此外，本发明还提供一种API文档生成设备，包括：

存储器，用于存储计算机程序；

处理器，用于执行计算机程序时实现如上述的API文档生成方法的步骤。

本发明所提供的API文档生成设备，首先获取API源代码，将源代码加载至IDEA集成开发环境中，并调用该IDEA集成开发环境的PSI程序结构接口对API源代码进行解析并生成对象树，进而提取对象树中各函数类中能够描述函数类的属性的元数据，并根据元数据生成API文档。本设备通过利用IDEA集成开发环境中的PSI程序结构接口对API源代码中各函数类的元数据进行提取，并以此生成API文档，进而无需以人工方式编写API文档，相对降低了产生API文档过程所需的人工成本，并保证了所生成的API文档的准确性。

此外，本发明还提供一种计算机可读存储介质，计算机可读存储介质上存储有计算机程序，计算机程序被处理器执行时实现如上述的API文档生成方法的步骤。

本发明所提供的计算机可读存储介质，首先获取API源代码，将源代码加载至IDEA集成开发环境中，并调用该IDEA集成开发环境的PSI程序结构接口对API源代码进行解析并生成对象树，进而提取对象树中各函数类中能够描述函数类的属性的元数据，并根据元数据生成API文档。本计算机可读存储介质通过利用IDEA集成开发环境中的PSI程序结构接口对API源代码中各函数类的元数据进行提取，并以此生成API文档，进而无需以人工方式编写API文档，相对降低了产生API文档过程所需的人工成本，并保证了所生成的API文档的准确性。

以上对本发明所提供的一种API文档生成方法、装置、设备及存储介质进行了详细介绍。说明书中各个实施例采用递进的方式描述，每个实施例重点说明的都是与其他实施例的不同之处，各个实施例之间相同相似部分互相参见即可。对于实施例公开的装置而言，由于其与实施例公开的方法相对应，所以描述的比较简单，相关之处参见方法部分说明即可。应当指出，对于本技术领域的普通技术人员来说，在不脱离本发明原理的前提下，还可以对本发明进行若干改进和修饰，这些改进和修饰也落入本发明权利要求的保护范围内。

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

Claims (10)

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

获取API源代码，并将所述API源代码加载至IDEA集成开发环境；

调用所述IDEA集成开发环境的PSI程序结构接口对所述API源代码进行解析以生成对象树；

提取所述对象树中各函数类的元数据，所述元数据为描述所述函数类的属性的数据；

根据所述元数据生成API文档。

2.根据权利要求1所述的API文档生成方法，其特征在于，在所述根据所述元数据生成API文档之前，所述方法还包括：

获取由用户设置的系统路径；

在所述根据所述元数据生成API文档之后，所述方法还包括：

将所述API文档存储至所述系统路径。

3.根据权利要求1所述的API文档生成方法，其特征在于，所述元数据包括注释、类名、方法名、输入参数以及返回参数。

4.根据权利要求3所述的API文档生成方法，其特征在于，当所述API源代码的语言类型为Java类型时，所述元数据还包括Javadoc。

5.根据权利要求1至4任意一项所述的API文档生成方法，其特征在于，在所述根据所述元数据生成API文档之前，所述方法还包括：

获取所述对象树中各所述函数类之间的结构关系；

所述根据所述元数据生成API文档，包括：

依照所述结构关系对各所述函数类的元数据进行组合以生成所述API文档。

6.一种API文档生成装置，其特征在于，包括：

源代码加载模块，用于获取API源代码，并将所述API源代码加载至IDEA集成开发环境；

接口调用模块，用于调用所述IDEA集成开发环境的PSI程序结构接口对所述API源代码进行解析以生成对象树；

元数据提取模块，用于提取所述对象树中各函数类的元数据，所述元数据为描述所述函数类的属性的数据；

文档生成模块，用于根据所述元数据生成API文档。

7.根据权利要求6所述的API文档生成装置，其特征在于，所述装置还包括：

路径获取模块，用于获取由用户设置的系统路径；

路径存储模块，用于将所述API文档存储至所述系统路径。

8.根据权利要求6或7所述的API文档生成装置，其特征在于，所述装置还包括：

关系获取模块，用于获取所述对象树中各所述函数类之间的结构关系；

所述文档生成模块，包括：

嵌套生成模块，用于依照所述结构关系对各所述函数类的元数据进行组合以生成所述API文档。

9.一种API文档生成设备，其特征在于，包括：

存储器，用于存储计算机程序；

处理器，用于执行所述计算机程序时实现如权利要求1至5任一项所述的API文档生成方法的步骤。

10.一种计算机可读存储介质，其特征在于，所述计算机可读存储介质上存储有计算机程序，所述计算机程序被处理器执行时实现如权利要求1至5任一项所述的API文档生成方法的步骤。

Images