CN107239271A - 开发文档生成方法及装置 - Google Patents

Abstract

本发明提供了一种开发文档生成方法及装置，所述方法包括：在预设程序开发管理工具中引入控制参数，控制参数用于在程序编译时将API程序中的每个方法中出现的参数的参数名称编译进与各个方法对应的类文件中；注入RequestMappingHandlerMapping获取API程序中每个方法的相关参数信息；相关参数信息包括URL、Controller、请求参数和返回Header类型；使用反射解析技术从请求参数中解析出参数名称、参数类型和参数注解内容；将API程序中每个方法的相关参数信息以及解析出的各种内容进行封装获得API开发文档。本发明能够自动生成开发文档，解决了开发文档需要手工编写的问题。

Description

开发文档生成方法及装置

技术领域

本发明涉及计算机技术领域，具体涉及一种开发文档生成方法及装置。

背景技术

当前，B\S架构的程序和APP端的程序越来越依赖于API(应用程序接口Application Programming Interface，简称API)的调用，API是一种使用Json\XML格式的接口，用于在客户端与服务端之间进行数据传输的技术。

当API开发完成后，需要由API开发人员手工编写API开发文档，API开发文档主要包括：接口路径、请求参数、方法类型、方法数据类型、压缩传输、缓存要求、返回数据样例、接口说明等等十几个字段。

由于API开发文档包含的内容较多，如果手工编写API开发文档，不但较为繁琐，工作效率低，浪费开发人员的宝贵时间，而且还容易出错。

发明内容

针对现有技术中的缺陷，本发明提供一种开发文档生成方法及装置，能够自动生成开发文档，解决了开发文档需要手工编写的问题。

为解决上述技术问题，本发明提供以下技术方案：

第一方面，本发明提供了一种开发文档生成方法，包括：

在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中；

注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息；其中，所述相关参数信息包括地址URL、控制器Controller、请求参数和返回处理器Header类型；

以及，使用反射解析技术从所述请求参数中解析出参数名称、参数类型和参数注解内容；

将API程序中每个方法的相关参数信息以及通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。

优选地，所述方法还包括：在预设程序上下文中添加预设对象，并为所述预设对象配置根路径，所述根路径为所述API开发文档的根路径；

根据所述根路径将所述API开发文档在浏览器中进行展示。

优选地，所述注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息，包括：

注入RequestMappingHandlerMapping，获取SpringMVC中所有添加RequestMapping注解的处理器Handler方法；

从添加RequestMapping注解的处理器Handler方法中获取该方法的相关参数信息。

优选地，所述方法还包括：为所述预设对象配置JavaDoc根路径，所述JavaDoc根路径用于支持用户在浏览器中浏览JavaDoc。

优选地，所述根据所述根路径将所述API开发文档在浏览器中进行展示，包括：

采用Java服务器页面JSP技术根据所述根路径将所述API开发文档在浏览器中进行动态展示。

优选地，所述方法还包括：为所述预设对象配置表现层框架组件，所述表现层框架组件包括BootStrap、jQuery和DataTables；所述表现层框架组件BootStrap、jQuery和DataTables，用于在展示所述API开发文档时，对所述API开发文档进行分页、组合搜索、筛选和/或排序。

优选地，所述方法还包括：为所述预设对象配置所述表现层框架组件的地址URL，作为所述表现层框架组件的备用访问地址。

优选地，所述预设程序开发管理工具包括Maven和/或Gradle。

第二方面，本发明还提供了一种开发文档生成装置，包括：

控制参数引入单元，用于在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中；

第一获取单元，用于注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息；其中，所述相关参数信息包括地址URL、控制器Controller、请求参数和返回处理器Header类型；

第二获取单元，用于使用反射解析技术从所述请求参数中解析出参数名称、参数类型和参数注解内容；

第三获取单元，用于将所述第一获取单元获取的API程序中每个方法的相关参数信息以及所述第二获取单元通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。

优选地，所述装置还包括：对象添加和配置单元和展示单元；

所述对象添加和配置单元，用于在预设程序上下文中添加预设对象，并为所述预设对象配置根路径，所述根路径为所述API开发文档的根路径；

所述展示单元，用于根据所述根路径将所述API开发文档在浏览器中进行展示。

由上述技术方案可知，本发明所述的开发文档生成方法，首先在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中，然后通过注入RequestMappingHandlerMapping的方式获取API的相关参数信息，并使用反射解析技术解析出参数名称、参数类型和参数注解内容，最后将API程序中每个方法的相关参数信息以及通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。可见，本实施例所述的开发文档生成方法，可以自动生成开发文档，无需人工编写，节省了人力成本，提高了效率。

另外，由于文档数据均为从程序代码中生成的数据，因此具有准确的特点，能够避免很多由于人工输入错误而导致的问题。

此外，由于文档数据均为运行时数据，会根据运行时数据实时生成，因为能够避免由于依赖环境没有更新而导致的文档不准确问题。

此外，由于文档是从代码中生成得来，不同环境的代码生成的文档可以做到差异化，方便测试线、正式线、发布线等等进行区别查看。

附图说明

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

图1是本发明第一个实施例提供的开发文档生成方法的流程图；

图2是本发明第二个实施例提供的开发文档生成方法的流程图；

图3是本发明第二个实施例提供的开发文档生成方法的时序工作示意图；

图4是本发明第七个实施例提供的开发文档生成装置的结构示意图；

图5是本发明第八个实施例提供的开发文档生成装置的结构示意图。

具体实施方式

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

图1示出了本发明第一个实施例提供的开发文档生成方法的流程图，参见图1，本发明第一个实施例提供的开发文档生成方法包括如下步骤：

步骤101：在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中。

在本步骤中，所述预设程序开发管理工具包括Maven和/或Gradle。例如，在Maven或Gradle进行Java编译时，加入-g控制参数，该控制参数可以在编译时API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中。当然也可以在预设程序开发管理工具加入其它控制参数，只要该控制参数能够在程序编译时将API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中就行。

步骤102：注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息；其中，所述相关参数信息包括地址URL、控制器Controller、请求参数和返回处理器Header类型。

在本步骤中，注入请求映射处理器的关系映射表RequestMappingHandlerMapping，获取SpringMVC中所有添加RequestMapping注解的处理器Handler方法，从添加RequestMapping注解的处理器Handler方法中获取该方法的相关参数信息。

其中，在SpringMVC中，控制器Controller负责处理由前置控制器DispatcherServlet分发的请求，它把用户请求的数据经过业务处理层处理之后封装成一个模型Model，然后再把该模型Model返回给对应的展示层View进行展示。另外，这里的URL表示请求路径或地址。

步骤103：使用反射解析技术从所述请求参数中解析出参数名称、参数类型和参数注解内容。

在本步骤中，由于上述步骤101在预设程序开发管理工具中引入了控制参数，使得API程序中的每个方法中出现的参数的参数名称信息编译进了与各个方法对应的类文件中，因此本步骤可以使用反射解析技术，从上述步骤102获得的请求参数中解析出参数名称、参数类型和参数注解内容。

其中，注解是java中一个技术，指在代码、函数上加上一些内容，可用于运行时解析、编译期检查等。

步骤104：将API程序中每个方法的相关参数信息以及通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。

在本步骤中，将步骤102获取的API程序中每个方法的相关参数信息以及步骤103通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容封装至Model中，得到API开发文档。

本实施例所述的开发文档生成方法，首先在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中，然后通过注入RequestMappingHandlerMapping的方式获取API的相关参数信息，并使用反射解析技术解析出参数名称、参数类型和参数注解内容，最后将API程序中每个方法的相关参数信息以及通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。可见，本实施例所述的开发文档生成方法，可以自动生成开发文档，无需人工编写，节省了人力成本，提高了效率。

需要说明的是，本实施例在预设程序开发管理工具中引入了控制参数，使得在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中，从而使得后边可以采用反射解析技术从获得的请求参数中解析出参数名称、参数类型和参数注解内容。本实施例的这种处理方式，使得API相关参数信息的获取变得简单易行。可见，控制参数的引入是一个必不可少且非常重要的步骤。

另外，由于文档数据均为从程序代码中生成的数据，因此具有准确的特点，能够避免很多由于人工输入错误而导致的问题。

此外，由于文档数据均为运行时数据，会根据运行时数据实时生成，因为能够避免由于依赖环境没有更新而导致的文档不准确问题。

此外，由于文档是从代码中生成得来，不同环境的代码生成的文档可以做到差异化，方便测试线、正式线、发布线等等进行区别查看。

从上面描述可知，在程序开发时，可以直接在代码上添加注解，在注解中描述API作用，然后应用本实施例所述的开发文档生成方法，可以自动生成开发文档，并会随着服务器的重启，可以实时、准确的生成更新后的开发文档，因此可以大大节省文档的维护人力，提升效率。

图2示出了本发明第二个实施例提供的开发文档生成方法的流程图，参见图2，本发明第二个实施例提供的开发文档生成方法除了包括上面所述的步骤之外，还包括如下步骤105。

步骤105：在预设程序上下文中添加预设对象，并为所述预设对象配置根路径，所述根路径为所述API开发文档的根路径；根据所述根路径将所述API开发文档在浏览器中进行展示。

在本步骤中，为了方便开发组中的其他相关开发人员、测试人员等人员查看该文档，可以考虑将步骤104获得的API开发文档放到一个公共文件里，并给出所述API开发文档的根路径，使得相关人员在浏览器中输入所述根路径时，能够随时查看所述API开发文档。

例如，在预设程序上下文application-Context中添加对象bean，并为对象bean配置根路径，该根路径为存放所述API开发文档的根路径。当然，根据需要还可以为对象bean配置其他参数，以实现其他相应功能，下面实施例有具体介绍。

例如，在将获取的API的相关参数信息以及获取的API程序中的注解内容封装至Model中之后，根据所述根路径将Model传递给展现层(浏览器)，使用展现层框架进行解析并显示。其中，具体的工作时序图可参见图3所示。

优选地，为了使相关用户可以查看到更为详细的JavaDoc文档信息，在本发明第三个实施例中，还可以为所述预设对象配置JavaDoc根路径，所述JavaDoc根路径用于支持用户在浏览器中浏览JavaDoc。例如，在application-Context中添加对象bean，并为对象bean配置JavaDoc根路径，该JavaDoc根路径中存放有所有JavaDoc文档信息。

优选地，为了提高用户体验，在本发明第四个实施例中，可以采用Java服务器页面JSP技术根据所述根路径将所述API开发文档在浏览器中进行动态展示。

优选地，为了进一步满足用户对文档的观看需求，在本发明第五个实施例中，还可以为所述预设对象配置表现层框架组件，所述表现层框架组件包括BootStrap、jQuery和DataTables；所述表现层框架组件BootStrap、jQuery和DataTables，用于在展示所述API开发文档时，对所述API开发文档进行分页、组合搜索、筛选和/或排序。

例如，在对所述API开发文档进行展示时，可以使用BootStrap进行样式处理，使用jQuery和DataTables来支持表格分页、搜索等功能。

优选地，为了避免出现项目不可访问内容分发网络CDN时，样式渲染不正常的现象，在本发明第六个实施例中，还可以为所述预设对象配置所述表现层框架组件的地址URL，作为所述表现层框架组件的备用访问地址。

从上述的描述可以看出，上述开发文档生成方法还可以根据需要定制相应的功能，例如根据需要在application-Context中添加对象bean，并为对象bean配置根路径、JavaDoc根路径、对象配置表现层框架组件等等，以实现相应的功能。

需要说明的是，本发明实施例所述的开发文档生成方法包含的所有步骤均通过Spring解耦，对业务代码没有侵入性。

从上述的描述可以看出，本发明实施例提供的开发文档生成方法，实现起来较为方便，只需引入控制参数(相当于引入依赖)，并在application-Context中添加对象bean，并为对象bean配置所需的内容即可完成接入工作，然后分别采用注入RequestMappingHandlerMapping以及反射解析的技术，获取API的相关参数信息以及API程序的相关注解内容，进而将API的相关参数信息以及API程序的相关注解内容进行组合封装，获得API开发文档。本发明实施例所述的开发文档生成方法根据代码自动生成开发文档，具有使用简单、文档准确、能够自动实时更新的特点。另外，本发明实施例所述的开发文档生成方法大大节省了人力成本，完全避免了因人工编写的API开发文档存在歧义而引起的不同部门或不同开发人员之间的沟通问题，同时具有准确、可扩展、不同环境文档可区分等优势。

在将本实施例所述的开发文档生成方法应用到实际开发项目后发现，本实施例所述的开发文档生成方法使得开发前端和开发后端的学习成本变低、项目接入成本变低。并且本实施例所述的开发文档生成方法易于扩展，能快速增加和定制相应的功能，满足用户需求。

本发明第七个实施例提供了一种开发文档生成装置，参见图4，包括：

控制参数引入单元41，用于在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中。例如，所述预设程序开发管理工具包括Maven和/或Gradle。

第一获取单元42，用于注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息；其中，所述相关参数信息包括地址URL、控制器Controller、请求参数和返回处理器Header类型。

第二获取单元43，用于使用反射解析技术从所述请求参数中解析出参数名称、参数类型和参数注解内容。

第三获取单元44，用于将所述第一获取单元42获取的API程序中每个方法的相关参数信息以及所述第二获取单元43通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。

本实施例所述的开发文档生成装置，可以用于执行上述第一个实施例所述的开发文档生成方法，其原理和技术效果类似，此处不再详述。

优选地，所述第一获取单元42，具体用于：

注入RequestMappingHandlerMapping，获取SpringMVC中所有添加RequestMapping注解的Handler方法；

通过RequestMappingHandlerMapping获取处理请求的相关参数信息。

在本发明第八个实施例中，参见图5，所述装置还包括：对象添加和配置单元45以及展示单元46；

所述对象添加和配置单元45，用于在预设程序上下文中添加预设对象，并为所述预设对象配置根路径，所述根路径为所述API开发文档的根路径；

所述展示单元46，用于根据所述根路径将所述API开发文档在浏览器中进行展示。

优选地，所述展示单元46，用于采用Java服务器页面JSP技术根据所述根路径将所述API开发文档在浏览器中进行动态展示。

优选地，所述对象添加和配置单元45，还用于：为所述预设对象配置JavaDoc根路径，所述JavaDoc根路径用于支持用户在浏览器中浏览JavaDoc。

优选地，所述对象添加和配置单元45，还用于：为所述预设对象配置表现层框架组件，所述表现层框架组件包括BootStrap、jQuery和DataTables；所述表现层框架组件BootStrap、jQuery和DataTables，用于在展示所述API开发文档时，对所述API开发文档进行分页、组合搜索、筛选和/或排序。

优选地，所述对象添加和配置单元45，还用于：为所述预设对象配置所述表现层框架组件的地址URL，作为所述表现层框架组件的备用访问地址。

以上实施例仅用于说明本发明的技术方案，而非对其限制；尽管参照前述实施例对本发明进行了详细的说明，本领域的普通技术人员应当理解：其依然可以对前述各实施例所记载的技术方案进行修改，或者对其中部分技术特征进行等同替换；而这些修改或替换，并不使相应技术方案的本质脱离本发明各实施例技术方案的精神和范围。

Claims (10)

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

在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中；

注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息；其中，所述相关参数信息包括地址URL、控制器Controller、请求参数和返回处理器Header类型；

以及，使用反射解析技术从所述请求参数中解析出参数名称、参数类型和参数注解内容；

将API程序中每个方法的相关参数信息以及通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。

2.根据权利要求1所述的方法，其特征在于，还包括：在预设程序上下文中添加预设对象，并为所述预设对象配置根路径，所述根路径为所述API开发文档的根路径；

根据所述根路径将所述API开发文档在浏览器中进行展示。

3.根据权利要求1所述的方法，其特征在于，所述注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息，包括：

注入RequestMappingHandlerMapping，获取SpringMVC中所有添加RequestMapping注解的处理器Handler方法；

从添加RequestMapping注解的处理器Handler方法中获取该方法的相关参数信息。

4.根据权利要求2所述的方法，其特征在于，还包括：为所述预设对象配置JavaDoc根路径，所述JavaDoc根路径用于支持用户在浏览器中浏览JavaDoc。

5.根据权利要求2所述的方法，其特征在于，所述根据所述根路径将所述API开发文档在浏览器中进行展示，包括：

采用Java服务器页面JSP技术根据所述根路径将所述API开发文档在浏览器中进行动态展示。

6.根据权利要求5所述的方法，其特征在于，还包括：为所述预设对象配置表现层框架组件，所述表现层框架组件包括BootStrap、jQuery和DataTables；所述表现层框架组件BootStrap、jQuery和DataTables，用于在展示所述API开发文档时，对所述API开发文档进行分页、组合搜索、筛选和/或排序。

7.根据权利要求6所述的方法，其特征在于，还包括：为所述预设对象配置所述表现层框架组件的地址URL，作为所述表现层框架组件的备用访问地址。

8.根据权利要求1所述的方法，其特征在于，所述预设程序开发管理工具包括Maven和/或Gradle。

9.一种开发文档生成装置，其特征在于，包括：

控制参数引入单元，用于在预设程序开发管理工具中引入控制参数，所述控制参数用于在程序编译时将应用程序接口API程序中的每个方法中出现的参数的参数名称信息编译进与各个方法对应的类文件中；

第一获取单元，用于注入请求映射处理器的关系映射表RequestMappingHandlerMapping，从RequestMappingHandlerMapping中获取API程序中每个方法的相关参数信息；其中，所述相关参数信息包括地址URL、控制器Controller、请求参数和返回处理器Header类型；

第二获取单元，用于使用反射解析技术从所述请求参数中解析出参数名称、参数类型和参数注解内容；

第三获取单元，用于将所述第一获取单元获取的API程序中每个方法的相关参数信息以及所述第二获取单元通过反射解析技术从每个方法的请求参数中解析出的参数名称、参数类型和参数注解内容进行封装处理，获得API开发文档。

10.根据权利要求9所述的装置，其特征在于，还包括：对象添加和配置单元和展示单元；

所述对象添加和配置单元，用于在预设程序上下文中添加预设对象，并为所述预设对象配置根路径，所述根路径为所述API开发文档的根路径；

所述展示单元，用于根据所述根路径将所述API开发文档在浏览器中进行展示。