一种基于注释和反射生成接口文档的方法与流程

1.本发明涉及计算机技术领域，具体是一种基于注释和反射生成接口文档的方法。


背景技术：

2.在一般的开发过程中，如果涉及到和其他系统进行交互的情况，则需要编写接口文档供用户进行参考开发，现有技术中，接口文档通过开发人员手工编写，缺点是手工编写工作量大，浪费了开发人员的开发时间。


技术实现要素：

3.本发明的目的在于提供一种基于注释和反射生成接口文档的方法，其通过系统启动事件在系统加载完成后扫描源代码中的所有接口类，将包含@restcontroller的接口类中需要暴露的方法解析成json数据保存在本地缓存中。开发人员可采用标准的javadoc注释配置查询条件和结果字段，在本发明的运行阶段，接口文档生成插件将动态地对查询条件和输出结果字段进行组装，再将组装好的接口描述信息返回到页面中获得接口文档，以解决上述背景技术中提出的问题。
4.为实现上述目的，本发明提供如下技术方案：
5.一种基于注释和反射生成接口文档的方法，包括以下步骤：
6.应用系统接收启动指令进行启动；
7.所述应用系统启动后对接口文档生成插件的applicationrunner接口的实现类进行调用，所述接口文档生成插件开始工作；
8.所述接口文档生成插件对所述应用系统的源码当中所有以controller结尾或者带有@restcontroller注解的类进行扫描，获取所述类的注释作为接口访问url的前缀；
9.所述接口文档生成插件对所述类所有的方法进行扫描，获取所述方法中的@requestmapping注解的value作为接口访问url的后缀以及获取所述@requestmapping注解中的methodtype作为方法访问的类型；
10.所述接口文档生成插件对所述类所有的方法的@param注释进行扫描，获取所述@param注释中的内容作为接口输入参数，然后通过竖杠对所述接口输入参数中的输入名称、中文名称、类型、是否必填以及备注进行分隔；
11.所述接口文档生成插件对所述类所有的方法的@return注释进行扫描并判定是否扫描到所述@return注释，是则获取所述@return注释作为所述接口文档生成插件的接口输出参数，否则所述接口文档生成插件利用反射对所述方法的返回对象进行获取并对所述返回对象属性的注释进行解析，获取所述注释的解析作为所述接口文档生成插件的接口输出参数；
12.所述接口文档生成插件将数据按照不同的接口分类存储到本地缓存中，其中所述数据包括接口访问url的前缀、接口访问url的后缀、方法访问的类型、接口输出参数和接口输出参数；
13.所述接口文档生成插件接收接口访问url的访问指令再根据其从所述本地缓存中获取相应的接口内容并将其组装作为接口文档，然后将其输出并呈现。
14.进一步地，所述接口文档生成插件接收下载指令再根据其利用模板生成技术进行生成并输出得到模板文件。
15.进一步地，所述模板文件为markdown文件或postman配置文件。
16.本发明的有益效果：
17.与现有技术相比，通过本发明无需专门为接口文档编写代码，在开发过程中只需按照标准的javadoc格式编写应用系统的注释，当启动应用系统时，其会启动接口文档生成插件开始工作，接口文档生成插件通过利用javadoc api和反射对应用系统当中的数据进行获取并将其保存到本地缓存中，数据包括接口访问url的前缀、接口访问url的后缀、方法访问的类型、接口输出参数和接口输出参数；
18.当用户在浏览器端输入接口访问url进行访问后，接口文档生成插件会自动将接口文档输出到浏览器端进行呈现，实现得到接口文档，接口文档上还显示了下载markdown文件或下载postman配置文件的下载按钮，用户通过鼠标指针对该下载按钮进行单击后，接口文档生成插件会根据本地缓存中的数据利用模板生成技术生成markdown文件或postman配置文件并其输出到浏览器端上。
附图说明
19.图1：本发明的方框流程示意图。
具体实施方式
20.以下结合附图对本发明进行进一步说明：
21.请参照图1，一种基于注释和反射生成接口文档的方法，包括以下步骤：
22.s1、应用系统接收启动指令进行启动；
23.s2、所述应用系统启动后对接口文档生成插件的applicationrunner接口的实现类进行调用，实现所述接口文档生成插件开始工作；
24.s3、所述接口文档生成插件对所述应用系统的源码当中所有以controller结尾或者带有@restcontroller注解的类进行扫描，获取所述类的注释作为接口访问url的前缀；
25.s4、所述接口文档生成插件对所述类所有的方法的@param注释进行扫描，获取所述@param注释中的内容作为接口输入参数，然后通过竖杠对所述接口输入参数中的输入名称、中文名称、类型、是否必填以及备注进行分隔，即输入名称|中文名称|类型|是否必填|备注；
26.s5、所述接口文档生成插件对所述类所有的方法进行扫描，获取所述方法中的@requestmapping注解的value作为接口访问url的后缀以及获取所述@requestmapping注解中的methodtype作为方法访问的类型，比如get、pos、put、delete等类型；
27.s6、所述接口文档生成插件对所述类所有的方法的@param注释进行扫描，获取所述@param注释中的内容作为接口输入参数，然后通过竖杠对所述接口输入参数中的输入名称、中文名称、类型、是否必填以及备注进行分隔；
28.s7、所述接口文档生成插件对所述类所有的方法的@return注释进行扫描并判定
是否扫描到所述@return注释，是则跳转步骤s7-1，否则跳转步骤s7-2；
29.s7-1、获取所述@return注释作为所述接口文档生成插件的接口输出参数，跳转步骤s8；
30.s7-2、所述接口文档生成插件利用反射对所述方法的返回对象进行获取并对所述返回对象属性的注释进行解析，获取所述注释的解析作为所述接口文档生成插件的接口输出参数，跳转步骤s8；
31.s8、所述接口文档生成插件将数据按照不同的接口分类存储到本地缓存中，其中所述数据包括接口访问url的前缀、接口访问url的后缀、方法访问的类型、接口输出参数和接口输出参数；
32.s9、所述接口文档生成插件接收来自浏览器端的接口访问url的访问指令并根据其从所述本地缓存中获取相应的接口内容且将其组装作为接口文档，然后将其输出并呈现在浏览器端；
33.s10、所述接口文档生成插件接收来自所述接口文档的下载指令再根据其利用模板生成技术生成模板文件将其并输出到浏览器端，其中所述模板文件为markdown文件或postman配置文件。
34.以上并非对本发明的技术范围作任何限制，凡依据本发明技术实质对以上的实施例所作的任何修改、等同变化与修饰，均仍属于本发明的技术方案的范围内。


技术特征：
1.一种基于注释和反射生成接口文档的方法，其特征在于：包括以下步骤：应用系统接收启动指令进行启动；所述应用系统启动后对接口文档生成插件的applicationrunner接口的实现类进行调用，所述接口文档生成插件开始工作；所述接口文档生成插件对所述应用系统的源码当中所有以controller结尾或者带有@restcontroller注解的类进行扫描，获取所述类的注释作为接口访问url的前缀；所述接口文档生成插件对所述类所有的方法进行扫描，获取所述方法中的@requestmapping注解的value作为接口访问url的后缀以及获取所述@requestmapping注解中的methodtype作为方法访问的类型；所述接口文档生成插件对所述类所有的方法的@param注释进行扫描，获取所述@param注释中的内容作为接口输入参数，然后通过竖杠对所述接口输入参数中的输入名称、中文名称、类型、是否必填以及备注进行分隔；所述接口文档生成插件对所述类所有的方法的@return注释进行扫描并判定是否扫描到所述@return注释，是则获取所述@return注释作为所述接口文档生成插件的接口输出参数，否则所述接口文档生成插件利用反射对所述方法的返回对象进行获取并对所述返回对象属性的注释进行解析，获取所述注释的解析作为所述接口文档生成插件的接口输出参数；所述接口文档生成插件将数据按照不同的接口分类存储到本地缓存中，其中所述数据包括接口访问url的前缀、接口访问url的后缀、方法访问的类型、接口输出参数和接口输出参数；所述接口文档生成插件接收接口访问url的访问指令再根据其从所述本地缓存中获取相应的接口内容并将其组装作为接口文档，然后将其输出并呈现。2.根据权利要求1所述的一种基于注释和反射生成接口文档的方法，其特征在于，还包括以下步骤：所述接口文档生成插件接收下载指令再根据其利用模板生成技术进行生成并输出得到模板文件。3.根据权利要求2所述的一种基于注释和反射生成接口文档的方法，其特征在于，所述模板文件为markdown文件或postman配置文件。

技术总结
本发明提供了一种基于注释和反射生成接口文档的方法，当启动应用系统时，其会启动接口文档生成插件开始工作，接口文档生成插件通过利用Javadoc API和反射对应用系统当中的数据进行获取并将其保存到本地缓存中，数据包括接口访问URL的前缀、接口访问URL的后缀、方法访问的类型、接口输出参数和接口输出参数；当用户在浏览器端输入接口访问URL进行访问后，接口文档生成插件会自动将接口文档输出到浏览器端进行呈现，实现得到接口文档，接口文档上还显示了下载Markdown文件或下载Postman配置文件的下载按钮，用户通过鼠标指针对该下载按钮进行单击后，接口文档生成插件会根据本地缓存中的数据利用模板生成技术生成Markdown文件或Postman配置文件并其输出到浏览器端上。上。上。


技术研发人员：罗挺
受保护的技术使用者：东莞数汇大数据有限公司
技术研发日：2021.11.01
技术公布日：2022/3/21