接口文档生成方法及装置与流程

1.本发明涉及软件开发技术领域，具体地，涉及一种接口文档生成方法及装置。


背景技术：

2.在软件开发过程中，尤其在使用第三方库或者组件的过程中，需要根据第三方库或者组件的接口文档进行开发，如jquery接口文档和javascript实用工具库lodash的文档等。通过使用接口文档，软件开发者可以快速进行软件开发。第三方库或者组件的提供者在软件代码完成编写后需要编写接口文档，便于使用库或者组件的开发者根据接口文档进行开发。
3.另外一个场景是在开发较大型软件时，通常项目组成员需要协同开发，项目中的开发人员需要调用其他开发人员的开发接口，此时也需要项目开发者提供完善的接口文档。
4.因此不管对于库、组件还是项目组内软件开发都需要提供详细的接口文档，便于其他软件开发人员快速开发系统和应用。接口文档内容编写需要做到准确、无遗漏、详细，软件接口内容更新时接口文档自动更新。接口文档这些特点需要提供接口的开发者在软件编写完成后再编写接口文档，为实现上述接口文档特点，需要接口提供者付出大量的时间和精力，增加了开发者的负担。


技术实现要素：

5.本发明实施例的主要目的在于提供一种接口文档生成方法及装置，以生成高效准确的接口文档。
6.为了实现上述目的，本发明实施例提供一种接口文档生成方法，包括：
7.将源代码转换为抽象语法树，确定抽象语法树中的函数代码；
8.解析从函数代码中提取的函数注释得到函数解析结果；
9.根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
10.本发明实施例还提供一种接口文档生成装置，包括：
11.语法树转换模块，用于将源代码转换为抽象语法树，确定抽象语法树中的函数代码；
12.解析模块，用于解析从函数代码中提取的函数注释得到函数解析结果；
13.接口文档生成模块，用于根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
14.本发明实施例还提供一种计算机设备，包括存储器、处理器及存储在存储器上并在处理器上运行的计算机程序，处理器执行计算机程序时实现所述的接口文档生成方法的步骤。
15.本发明实施例还提供一种计算机可读存储介质，其上存储有计算机程序，计算机
程序被处理器执行时实现所述的接口文档生成方法的步骤。
16.本发明实施例还提供一种计算机程序产品，包括计算机程序/指令，该计算机程序/指令被处理器执行时实现如上所述的接口文档生成方法的步骤。
17.本发明实施例的接口文档生成方法及装置先将源代码转换为抽象语法树以确定抽象语法树中的函数代码，然后解析从函数代码中提取的函数注释得到函数解析结果，最后根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成高效准确的接口文档。
附图说明
18.为了更清楚地说明本发明实施例或现有技术中的技术方案，下面将对实施例描述中所需要使用的附图作简单地介绍，显而易见地，下面描述中的附图仅仅是本发明的一些实施例，对于本领域普通技术人员来讲，在不付出创造性劳动的前提下，还可以根据这些附图获得其他的附图。
19.图1是本发明实施例中接口文档生成方法的流程图；
20.图2是本发明另一实施例中接口文档生成方法的流程图；
21.图3是本发明实施例中接口文档生成装置的结构框图；
22.图4是本发明实施例中计算机设备的结构框图。
具体实施方式
23.下面将结合本发明实施例中的附图，对本发明实施例中的技术方案进行清楚、完整地描述，显然，所描述的实施例仅仅是本发明一部分实施例，而不是全部的实施例。基于本发明中的实施例，本领域普通技术人员在没有做出创造性劳动前提下所获得的所有其他实施例，都属于本发明保护的范围。
24.本领域技术人员知道，本发明的实施方式可以实现为一种系统、装置、设备、方法或计算机程序产品。因此，本公开可以具体实现为以下形式，即：完全的硬件、完全的软件(包括固件、驻留软件、微代码等)，或者硬件和软件结合的形式。
25.鉴于目前需要接口提供者付出大量的时间和精力编写接口文档，增加了开发者的负担，本发明实施例提供一种接口文档生成方法，以基于高度可定制的插件配置信息和javascript注释自动生成高效准确的接口文档。以下结合附图对本发明进行详细说明。
26.本发明主要使用的技术包括webpack和babel。
27.1、webpack是一个用于现代javascript应用程序的静态模块打包器，可以打包web应用资源(包括样式文件、javascript文件、图片文件和字体文件)到一个或者多个文件中，web应用可以直接引入打包后的文件。打包的过程包括资源压缩(如将图片资源、javascript文件和样式文件等文件的体积减小)、资源转换(如将高版本的javascript代码转换为低版本代码，目的是在低版本的浏览器下也可以正常运行javascript代码；将sass和less等css预编译语言编译为css语言)和资源的合并(如将多张图片合并为一张图片，即雪碧图)等。使用webpack打包web应用可以提升web应用的性能(如静态资源的体积小，网页加载就快；雪碧图减少网页请求图片的请求数)和兼容性(高版本的javascript代码不能直接运行在低版本的浏览器)。
28.本发明使用的webpack loader会解析软件代码中的javascript文件函数注释信息，同时可以配置插件输出接口文档名称、接口描述、接口参数、接口返回值、接口作者、接口是否弃用、接口版本、接口完成时间和接口额外说明信息等。
29.2、babel是一个javascript编译器，主要用于将ecmascript 2015+版本的代码转换为向后兼容的javascript语法，以便能够运行在当前和旧版本的浏览器或其他环境中。本发明采用babel插件，可以遍历项目中的javascript代码，根据开发者在loader中的配置信息和函数注释自动生成接口文档。
30.图1是本发明实施例中接口文档生成方法的流程图。图2是本发明另一实施例中接口文档生成方法的流程图。如图1和图2所示，接口文档生成方法包括：
31.s101：将源代码转换为抽象语法树，确定抽象语法树中的函数代码。
32.如图2所示，接口文档生成方法主要包括三部分，分别是获取插件配置参数、解析源代码(javascript代码)和生成接口文档。
33.javascript注释分为单行注释和多行注释。其中单行注释以字符//开头，因单行注释无法包含多个信息，因此本发明源代码中的javascript注释都是多行注释。
34.源代码中的javascript注释需要按照如下格式设置：
35.1、对于方法的描述，如“长方形面积”，在函数注释前些即可，可以多行。
36.2、函数参数可以不包括参数，也可以含有多个参数。对于多个参数的情形，源代码和对应生成的接口文档均为每个参数书写一行。
37.以“*@param{number}a长度”为例，@param是参数标识，以@符号开始；符号{}中的内容是参数的类型，如number表示数字类型；“a”是参数的名称；“长度”是参数的含义，参数的每个信息以空格分隔。
38.3、函数返回值可以不包括返回值，也可以只有一个返回值。针对无返回值情况(即函数体内无return关键字)，函数的返回值就是“undefined”。
39.以“*@returns{number}s长方形的面积”为例，针对有返回值的情况，@returns是参数标识，以@符号开始；符号{}中的内容是返回值的类型，如number表示数字类型；“s”是返回值的名称；“长方形的面积”是返回值的含义，返回值的每个信息以空格分隔。
40.4、开发者、版本、更新时间、函数是否废弃和额外信息等注释的格式一致。如“*@author dever”，其中@author是接口开发者标识，以@符号开始；dever是开发者内容。
41.5、@apioutput为是否输出到接口文档的标识，若标识后的内容为true或者接口注释中没有@apioutput，表示本接口信息会输出到接口文档中。若某方法的注释中有@apioutput false信息，则此接口注释内容不会提取到接口文档中。
42.抽象语法树(ast，abstract syntax code)将源代码抽象为树状结构表示，是一个属性的json结构对象，可以描述源代码的信息。本发明使用“@babel/parser”库将输入的源代码代码转换为抽象语法树，抽象语法树中的commentblock(函数块状注释)内容是是本发明核心要处理的节点。
43.一实施例中，确定抽象语法树中的函数代码包括：使用“@babel/traverse”库对ast执行遍历操作，找到需要处理接口注释代码，提取函数代码。
44.抽象语法树包括多种节点类型，如数组类型、对象类型、函数类型和布尔类型等。本发明对抽象语法树中函数类型进行处理，因为接口就是函数。
45.在javascript语言中，函数代码的表示形式包括函数声明、函数表达式、箭头函数和类函数，具体如下：
46.1、函数声明：函数声明是javascript中使用function关键词定义函数。
47.2、函数表达式：将函数定义赋值到变量上可以得到函数表达式。
48.3、箭头函数：箭头函数(arrow function)是es6新增的一种函数。
49.箭头函数一般用作函数回调，无法被外部函数调用，因此本发明不处理箭头函数。
50.4、类函数(class)：类函数是javascript的一种定义类型的方法，包括实例方法和静态方法。
51.上述代码中的tostring是一个实例方法，classmethod是静态方法(即静态方法前有static关键字)。
52.一实施例中，确定抽象语法树中的函数代码包括：使用“@babel/traverse”库对ast执行遍历操作，找到需要处理接口注释代码，提取函数代码。其中“functiondeclaration”是处理函数声明的代码，“variabledeclaration”是处理函数表达式的代码，“classmethod”是处理类函数的函数代码，“generateapi”是处理函数注释模块的逻辑。
53.s102：解析从函数代码中提取的函数注释得到函数解析结果。
54.一实施例中，从函数代码中提取函数注释包括：
55.确定函数代码的函数类型：根据函数类型确定函数代码的前注释字段；从函数代码的前注释字段中提取函数注释。
56.其中，函数代码包括函数声明、函数表达式和类函数；函数注释包括函数声明注释、函数表达式注释和类函数注释，可以在函数前，函数体内或函数后。
57.本发明需要提取注释到接口文档的注释默认都是函数前注释。
58.从函数代码的前注释字段中提取函数注释包括：
59.1、从函数声明代码的前注释字段中提取函数声明注释，函数声明注释(value)从leadingcomments字段获取。
60.2、从变量声明节点的前注释字段中提取函数表达式注释。
61.一实施例中，从变量声明节点的前注释字段中提取函数表达式注释包括：
62.获取函数表达式代码的变量声明节点类型，根据变量声明节点类型从变量声明节点的前注释字段中提取函数表达式注释。
63.函数表达式的节点类型是functionexpression，但是函数表达式前的注释是在variabledeclaration(变量声明)节点上，因此抽象语法树在处理functionexpression时需要处理的是变量声明节点。变量声明节点的内容不一定是函数声明，因此需要通过插件判断变量声明节点的内容是函数声明时才从变量声明节点的前注释字段leadingcomments中获取函数表达式注释。
64.具体实施时，先从函数表达式代码的初始化节点init下获取函数表达式代码的变量声明节点类型；当变量声明节点类型与函数表达式对应时，从变量声明节点的前注释字段中提取函数表达式注释。
65.当init下的变量声明节点类型type为functionexpression时，表明变量声明节点的内容是函数声明，此时从变量声明节点的前注释字段leadingcomments中获取函数表达
式注释。
66.3、从类函数代码的前注释字段中提取类函数注释。
67.类函数的节点类型是classmethod，但是类函数前的注释是在leadingcomments字段上，类函数注释(value)从leadingcomments字段获取。
68.具体实施时，可以通过comment-parser库解析从函数代码中提取的函数注释得到函数解析结果，包括tags字段。tags字段是一个数组，tags包含注释中所有以@字符开始的信息。
69.s103：根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
70.本发明中的插件可以接收开发者传入的参数，根据插件配置参数进行javascript代码(源代码)的解析。插件参数包括：filename，apioutput，param，returns，author，deprecated，version，date和extraparameters。插件使用者在使用插件时可以使用loader-utils库获取插件配置信息。
71.1、filename是输出接口文档的文件名，默认是api.md。插件使用者可以配置为其他文件名，插件在执行时接收到开发者配置的filename，将接口信息写入到filename中。
72.2、apioutput决定接口是否输出到接口文档中，类型是布尔值，即只有true和false两种，默认是true。若插件开发者在某个方法的注释中配置apioutput为false，则插件在解析到这个方法注释时不会处理对应的注释信息，即不会提取注释信息到接口文档。
73.3、param，returns，author，deprecated，version和date字段的配置类似。插件开发者也可以配置为其他字符串，如：param:parameter，此时插件在解析javascript代码时，会从代码注释中的@parameter获取方法的参数信息。
74.4、extraparameters允许插件使用者配置额外信息。extraparameters类型是一个对象，对象内容是开发者配置的额外信息，如额外信息字段team。若注释中存在team信息，如@team：“团队a”，则插件会将团队信息输出到接口文档中。
75.插件使用者在使用插件时可以使用loader-utils库获取插件配置信息，在web应用安装插件，在webpack中配置插件参数，核心配置如下代码所示，令项目构建后自动生成接口文档：
76.一实施例中，提取函数名称包括：确定函数代码的函数类型：根据函数类型确定函数代码的id节点；从id节点的姓名属性中提取函数名称。
77.其中，函数名称包括函数声明名称、函数表达式名称和类函数名称。
78.一实施例中，根据函数类型确定函数代码的id节点包括：
79.1、从函数声明代码中确定函数声明代码的id节点。
80.当函数注释为函数声明注释时，对应的函数名称为函数声明名称，此时从函数声明代码id节点的姓名属性(name)中获取函数声明名称(rectangulararea)。
81.2、从函数表达式代码的变量声明节点中确定函数表达式代码的id节点。
82.当函数注释为函数表达式注释时，对应的函数名称为函数表达式名称，此时从函数表达式代码的变量声明节点(variabledeclaration)下id节点的姓名属性(name)中获取函数表达式名称(rectangulararea)。
83.3、确定类函数代码的键值节点为类函数代码的id节点。
84.当函数注释为类函数注释时，对应的函数名称为类函数名称，此时从类函数代码键值节点(key)的姓名属性(name)中获取类函数名称(sleep)。
85.如函数解析结果的代码所示，本发明获取的注释信息包括：
86.1、接口是否输出到文档
87.是否输出到文档从函数解析结果的apioutput字段获取。若apioutput的description为“false”，表示本接口不需要输出到接口文档，继续后续注释处理。
88.2、函数描述
89.函数描述从函数解析结果的description字段获取。
90.3、函数参数
91.因为函数可能有多个参数，所以在tags数组中，可能存在多个tag值为“param”(若插件开发者配置参数的名称为parameter，此时tags数组中就有多个tag值为“parameter”)，从每一个tag值为“param”的对象的name属性中提取参数名称，从每一个tag值为“param”的对象的type属性中提取参数类型，从每一个tag值为“param”的对象的description属性中提取参数描述。
92.4、函数返回值
93.函数返回值从tags数组中tag值为“returns”的元素中获取(若插件开发者配置返回值的名称为returntest，则此时tags数组中有一个tag值为“returntest”的元素，函数返回值从tag值为“returntest”的元素中获取信息)，从tag值为“returns”的对象的name属性中提取返回值名称，从tag值为“returns”的对象的type属性中提取返回值类型，从tag值为“returns”的对象的description属性中提取返回值描述。
94.5、author，deprecated，version和date
95.函数的author，deprecated，version和date分别从tags数组中tag值为“author”、“deprecated”、“version”和“date”中获取(同样若设置为其他字符串，信息从其他字符串获取)，分别从相应tag的name属性中提取作者、是否废弃、版本和时间信息。
96.6、额外信息
97.根据插件配置的额外信息(如team)，从tags数组中tag值为“team”的name属性获取额外信息值。
98.具体实施时，将注释信息和对应的函数名称输入文档模板中生成接口文档包括：将注释信息和对应的函数名称输入文档模板(markdown模板)中生成接口描述的字符，根据插件配置的filename文件名，使用node将接口描述的字符生成到根目录下的filename文件中得到接口文档。
99.图1所示的接口文档生成方法的执行主体可以为计算机。由图1所示的流程可知，本发明实施例的接口文档生成方法先将源代码转换为抽象语法树以确定抽象语法树中的函数代码，然后解析从函数代码中提取的函数注释得到函数解析结果，最后根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成高效准确的接口文档。
100.本发明实施例的具体流程如下：
101.1、将源代码转换为抽象语法树，确定抽象语法树中的函数代码。
102.2、确定函数代码的函数类型，根据函数类型确定函数代码的前注释字段。
103.3、
①
从函数声明代码的前注释字段中提取函数声明注释；或
104.②
从函数表达式代码的初始化节点下获取函数表达式代码的变量声明节点类型；
105.当变量声明节点类型与函数表达式对应时，从变量声明节点的前注释字段中提取函数表达式注释；或
106.③
从类函数代码的前注释字段中提取类函数注释。
107.4、解析从函数代码中提取的函数注释得到函数解析结果
108.5、
①
从函数声明代码中确定函数声明代码的id节点；或
109.②
从函数表达式代码的变量声明节点中确定函数表达式代码的id节点；或
110.③
确定类函数代码的键值节点为类函数代码的id节点
111.6、从id节点的姓名属性中提取函数名称。
112.7、根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
113.综上所述，本发明实施例提供的接口文档生成方法具有以下有益效果：
114.(1)高度可定制。
115.1、接口文档可定制文档输出文件名称和文件格式，默认文件名是api，文档格式是markdown文件。
116.2、可以实现某个接口内容是否输出到接口文档，即不将某个接口信息输出到接口文档。
117.3、接口内容可定制。接口内容包括接口名、接口描述、接口参数、接口返回值、接口作者、接口是否弃用(已经废弃，而且在将来的代码版本中将彻底删除。要避免使用这段代码)、接口版本、接口完成时间和接口额外信息说明。接口内容可定制包括在三个方面，一是接口名、接口描述、接口参数、接口返回值、接口作者、接口是否弃用、接口版本和接口完成时间这些字段可根据是否在代码注释中有无，自动在接口文档中体现，如若某接口注释中未写接口版本内容，则接口文档中某接口的信息就不包括接口版本。二是接口参数、接口返回值、接口作者、接口是否弃用、接口版本和接口完成时间有默认的标识，本发明中上述内容的默认标识是：接口参数(param)、接口返回值(returns)、接口作者(author)、接口是否弃用(deprecated)、接口版本(version)和接口完成时间(time)。开发者可以根据个人需求修改为其他标识，如将接口参数标识需要修改为parameter，开发者在javascript代码的注释中可以使用@parameter来描述接口参数信息。三是支持扩展字段，如添加软件许可(license)，开发者可以配置额外信息，在开发某个接口时在接口注释中添加额外信息标识和内容，接口文档会自动添加额外信息。
118.(2)接口文档准确、无遗漏。本发明通过遍历javascript语言编写的软件代码，根据接口注释自动生成接口文档。接口文档准确无遗漏，避免了人为操作造成遗漏的风险，同时减轻了接口开发人员的工作压力，在软件代码修改注释后自动同步修改了接口文档，保证接口文档和代码的一致性。
119.(3)高效。接口提供者只需要在编写软件代码过程中添加接口注释，运行插件接口文档即可自动生成。当接口提供者在修改某个接口文档注释时，接口文档会同步更新。保证接口文档的准确性和更新及时性。
120.基于同一发明构思，本发明实施例还提供了一种接口文档生成装置，由于该装置
解决问题的原理与接口文档生成方法相似，因此该装置的实施可以参见方法的实施，重复之处不再赘述。
121.图3是本发明实施例中接口文档生成装置的结构框图。如图3所示，接口文档生成装置包括：
122.语法树转换模块，用于将源代码转换为抽象语法树，确定抽象语法树中的函数代码；
123.解析模块，用于解析从函数代码中提取的函数注释得到函数解析结果；
124.接口文档生成模块，用于根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
125.在其中一种实施例中，还包括函数注释提取模块，函数注释提取模块包括：
126.函数类型确定单元，用于确定函数代码的函数类型：
127.前注释字段确定单元，用于根据函数类型确定函数代码的前注释字段；
128.函数注释提取单元，用于从函数代码的前注释字段中提取函数注释。
129.在其中一种实施例中，函数注释提取单元包括：
130.函数声明注释提取子单元，用于从函数声明代码的前注释字段中提取函数声明注释；
131.函数表达式注释提取子单元，用于从变量声明节点的前注释字段中提取函数表达式注释；或
132.类函数注释提取子单元，用于从类函数代码的前注释字段中提取类函数注释。
133.在其中一种实施例中，函数表达式注释提取子单元具体用于：
134.获取函数表达式代码的变量声明节点类型，根据变量声明节点类型从变量声明节点的前注释字段中提取函数表达式注释。
135.在其中一种实施例中，函数表达式注释提取子单元具体用于：
136.从函数表达式代码的初始化节点下获取函数表达式代码的变量声明节点类型；
137.当变量声明节点类型与函数表达式对应时，从变量声明节点的前注释字段中提取函数表达式注释。
138.在其中一种实施例中，还包括函数名称提取模块，用于提取函数名称，包括：
139.函数类型确定单元，用于确定函数代码的函数类型：
140.id节点确定单元，用于根据函数类型确定函数代码的id节点；
141.函数名称提取单元，用于从id节点的姓名属性中提取函数名称。
142.在其中一种实施例中，id节点确定单元具体用于：
143.从函数声明代码中确定函数声明代码的id节点；或
144.从函数表达式代码的变量声明节点中确定函数表达式代码的id节点；或
145.确定类函数代码的键值节点为类函数代码的id节点。
146.综上，本发明实施例的接口文档生成装置先将源代码转换为抽象语法树以确定抽象语法树中的函数代码，然后解析从函数代码中提取的函数注释得到函数解析结果，最后根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成高效准确的接口文档。
147.本发明实施例还提供能够实现上述实施例中的接口文档生成方法中全部步骤的
一种计算机设备的具体实施方式。图4是本发明实施例中计算机设备的结构框图，参见图4，所述计算机设备具体包括如下内容：
148.处理器(processor)401和存储器(memory)402。
149.所述处理器401用于调用所述存储器402中的计算机程序，所述处理器执行所述计算机程序时实现上述实施例中的接口文档生成方法中的全部步骤，例如，所述处理器执行所述计算机程序时实现下述步骤：
150.将源代码转换为抽象语法树，确定抽象语法树中的函数代码；
151.解析从函数代码中提取的函数注释得到函数解析结果；
152.根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
153.本发明实施例的计算机设备先将源代码转换为抽象语法树以确定抽象语法树中的函数代码，然后解析从函数代码中提取的函数注释得到函数解析结果，最后根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成高效准确的接口文档。
154.本发明实施例还提供能够实现上述实施例中的接口文档方法中全部步骤的一种计算机可读存储介质，所述计算机可读存储介质上存储有计算机程序，该计算机程序被处理器执行时实现上述实施例中的接口文档方法的全部步骤，例如，所述处理器执行所述计算机程序时实现下述步骤：
155.将源代码转换为抽象语法树，确定抽象语法树中的函数代码；
156.解析从函数代码中提取的函数注释得到函数解析结果；
157.根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
158.本发明实施例的计算机可读存储介质先将源代码转换为抽象语法树以确定抽象语法树中的函数代码，然后解析从函数代码中提取的函数注释得到函数解析结果，最后根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成高效准确的接口文档。
159.本发明实施例还提供能够实现上述实施例中的接口文档方法中全部步骤的一种计算机程序产品，所述计算机程序产品包括计算机程序/指令，该计算机程序/指令被处理器执行时实现上述实施例中的接口文档方法的全部步骤，例如，该计算机程序/指令被处理器执行时实现下述步骤：
160.将源代码转换为抽象语法树，确定抽象语法树中的函数代码；
161.解析从函数代码中提取的函数注释得到函数解析结果；
162.根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成接口文档。
163.本发明实施例的计算机程序产品先将源代码转换为抽象语法树以确定抽象语法树中的函数代码，然后解析从函数代码中提取的函数注释得到函数解析结果，最后根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成高效准确的接口文档。
164.以上所述的具体实施例，对本发明的目的、技术方案和有益效果进行了进一步详
细说明，所应理解的是，以上所述仅为本发明的具体实施例而已，并不用于限定本发明的保护范围，凡在本发明的精神和原则之内，所做的任何修改、等同替换、改进等，均应包含在本发明的保护范围之内。
165.本领域技术人员还可以了解到本发明实施例列出的各种说明性逻辑块(illustrative logical block)，单元，和步骤可以通过电子硬件、电脑软件，或两者的结合进行实现。为清楚展示硬件和软件的可替换性(interchangeability)，上述的各种说明性部件(illustrative components)，单元和步骤已经通用地描述了它们的功能。这样的功能是通过硬件还是软件来实现取决于特定的应用和整个系统的设计要求。本领域技术人员可以对于每种特定的应用，可以使用各种方法实现所述的功能，但这种实现不应被理解为超出本发明实施例保护的范围。
166.本发明实施例中所描述的各种说明性的逻辑块，或单元，或装置都可以通过通用处理器，数字信号处理器，专用集成电路(asic)，现场可编程门阵列或其它可编程逻辑装置，离散门或晶体管逻辑，离散硬件部件，或上述任何组合的设计来实现或操作所描述的功能。通用处理器可以为微处理器，可选地，该通用处理器也可以为任何传统的处理器、控制器、微控制器或状态机。处理器也可以通过计算装置的组合来实现，例如数字信号处理器和微处理器，多个微处理器，一个或多个微处理器联合一个数字信号处理器核，或任何其它类似的配置来实现。
167.本发明实施例中所描述的方法或算法的步骤可以直接嵌入硬件、处理器执行的软件模块、或者这两者的结合。软件模块可以存储于ram存储器、闪存、rom存储器、eprom存储器、eeprom存储器、寄存器、硬盘、可移动磁盘、cd-rom或本领域中其它任意形式的存储媒介中。示例性地，存储媒介可以与处理器连接，以使得处理器可以从存储媒介中读取信息，并可以向存储媒介存写信息。可选地，存储媒介还可以集成到处理器中。处理器和存储媒介可以设置于asic中，asic可以设置于用户终端中。可选地，处理器和存储媒介也可以设置于用户终端中的不同的部件中。
168.在一个或多个示例性的设计中，本发明实施例所描述的上述功能可以在硬件、软件、固件或这三者的任意组合来实现。如果在软件中实现，这些功能可以存储与电脑可读的媒介上，或以一个或多个指令或代码形式传输于电脑可读的媒介上。电脑可读媒介包括电脑存储媒介和便于使得让电脑程序从一个地方转移到其它地方的通信媒介。存储媒介可以是任何通用或特殊电脑可以接入访问的可用媒体。例如，这样的电脑可读媒体可以包括但不限于ram、rom、eeprom、cd-rom或其它光盘存储、磁盘存储或其它磁性存储装置，或其它任何可以用于承载或存储以指令或数据结构和其它可被通用或特殊电脑、或通用或特殊处理器读取形式的程序代码的媒介。此外，任何连接都可以被适当地定义为电脑可读媒介，例如，如果软件是从一个网站站点、服务器或其它远程资源通过一个同轴电缆、光纤电缆、双绞线、数字用户线(dsl)或以例如红外、无线和微波等无线方式传输的也被包含在所定义的电脑可读媒介中。所述的碟片(disk)和磁盘(disc)包括压缩磁盘、镭射盘、光盘、dvd、软盘和蓝光光盘，磁盘通常以磁性复制数据，而碟片通常以激光进行光学复制数据。上述的组合也可以包含在电脑可读媒介中。

技术特征：
1.一种接口文档生成方法，其特征在于，包括：将源代码转换为抽象语法树，确定所述抽象语法树中的函数代码；解析从函数代码中提取的函数注释得到函数解析结果；根据插件配置参数从所述函数解析结果中获取注释信息，将所述注释信息和对应的函数名称输入文档模板中生成接口文档。2.根据权利要求1所述的接口文档生成方法，其特征在于，从函数代码中提取函数注释包括：确定所述函数代码的函数类型：根据所述函数类型确定所述函数代码的前注释字段；从所述函数代码的前注释字段中提取函数注释。3.根据权利要求2所述的接口文档生成方法，其特征在于，从所述函数代码的前注释字段中提取函数注释包括：从函数声明代码的前注释字段中提取函数声明注释；或从变量声明节点的前注释字段中提取函数表达式注释；或从类函数代码的前注释字段中提取类函数注释。4.根据权利要求3所述的接口文档生成方法，其特征在于，从变量声明节点的前注释字段中提取函数表达式注释包括：获取函数表达式代码的变量声明节点类型，根据所述变量声明节点类型从变量声明节点的前注释字段中提取函数表达式注释。5.根据权利要求4所述的接口文档生成方法，其特征在于，获取函数表达式代码的变量声明节点类型，根据所述变量声明节点类型从变量声明节点的前注释字段中提取函数表达式注释包括：从函数表达式代码的初始化节点下获取函数表达式代码的变量声明节点类型；当所述变量声明节点类型与函数表达式对应时，从变量声明节点的前注释字段中提取函数表达式注释。6.根据权利要求1所述的接口文档生成方法，其特征在于，提取函数名称包括：确定所述函数代码的函数类型：根据所述函数类型确定所述函数代码的id节点；从所述id节点的姓名属性中提取函数名称。7.根据权利要求6所述的接口文档生成方法，其特征在于，根据所述函数类型确定所述函数代码的id节点包括：从函数声明代码中确定函数声明代码的id节点；或从函数表达式代码的变量声明节点中确定函数表达式代码的id节点；或确定类函数代码的键值节点为类函数代码的id节点。8.一种接口文档生成装置，其特征在于，包括：语法树转换模块，用于将源代码转换为抽象语法树，确定所述抽象语法树中的函数代码；解析模块，用于解析从函数代码中提取的函数注释得到函数解析结果；接口文档生成模块，用于根据插件配置参数从所述函数解析结果中获取注释信息，将
所述注释信息和对应的函数名称输入文档模板中生成接口文档。9.根据权利要求8所述的接口文档生成装置，其特征在于，还包括函数注释提取模块，所述函数注释提取模块包括：函数类型确定单元，用于确定所述函数代码的函数类型：前注释字段确定单元，用于根据所述函数类型确定所述函数代码的前注释字段；函数注释提取单元，用于从所述函数代码的前注释字段中提取函数注释。10.根据权利要求9所述的接口文档生成装置，其特征在于，所述函数注释提取单元包括：函数声明注释提取子单元，用于从函数声明代码的前注释字段中提取函数声明注释；函数表达式注释提取子单元，用于从变量声明节点的前注释字段中提取函数表达式注释；或类函数注释提取子单元，用于从类函数代码的前注释字段中提取类函数注释。11.根据权利要求10所述的接口文档生成装置，其特征在于，所述函数表达式注释提取子单元具体用于：获取函数表达式代码的变量声明节点类型，根据所述变量声明节点类型从变量声明节点的前注释字段中提取函数表达式注释。12.根据权利要求11所述的接口文档生成装置，其特征在于，所述函数表达式注释提取子单元具体用于：从函数表达式代码的初始化节点下获取函数表达式代码的变量声明节点类型；当所述变量声明节点类型与函数表达式对应时，从变量声明节点的前注释字段中提取函数表达式注释。13.根据权利要求8所述的接口文档生成装置，其特征在于，还包括函数名称提取模块，用于提取函数名称，包括：函数类型确定单元，用于确定所述函数代码的函数类型：id节点确定单元，用于根据所述函数类型确定所述函数代码的id节点；函数名称提取单元，用于从所述id节点的姓名属性中提取函数名称。14.根据权利要求13所述的接口文档生成装置，其特征在于，所述id节点确定单元具体用于：从函数声明代码中确定函数声明代码的id节点；或从函数表达式代码的变量声明节点中确定函数表达式代码的id节点；或确定类函数代码的键值节点为类函数代码的id节点。15.一种计算机设备，包括存储器、处理器及存储在存储器上并在处理器上运行的计算机程序，其特征在于，所述处理器执行所述计算机程序时实现权利要求1至7任一项所述的接口文档生成方法的步骤。16.一种计算机可读存储介质，其上存储有计算机程序，其特征在于，所述计算机程序被处理器执行时实现权利要求1至7任一项所述的接口文档生成方法的步骤。17.一种计算机程序产品，包括计算机程序/指令，其特征在于，该计算机程序/指令被处理器执行时实现权利要求1至7任一项所述的接口文档生成方法的步骤。

技术总结
本发明提供一种接口文档生成方法及装置，该接口文档生成方法包括：将源代码转换为抽象语法树，确定抽象语法树中的函数代码；解析从函数代码中提取的函数注释得到函数解析结果；根据插件配置参数从函数解析结果中获取注释信息，将注释信息和对应的函数名称输入文档模板中生成高效准确接口文档。板中生成高效准确接口文档。板中生成高效准确接口文档。


技术研发人员：孟繁贵
受保护的技术使用者：中国建设银行股份有限公司
技术研发日：2021.12.03
技术公布日：2022/3/8