CN107515771A - 基于SpringMVC的API文档生成方法及系统 - Google Patents
基于SpringMVC的API文档生成方法及系统 Download PDFInfo
- Publication number
- CN107515771A CN107515771A CN201710800995.3A CN201710800995A CN107515771A CN 107515771 A CN107515771 A CN 107515771A CN 201710800995 A CN201710800995 A CN 201710800995A CN 107515771 A CN107515771 A CN 107515771A
- Authority
- CN
- China
- Prior art keywords
- api
- self
- service end
- springmvc
- document
- Prior art date
- Legal status (The legal status is an assumption and is not a legal conclusion. Google has not performed a legal analysis and makes no representation as to the accuracy of the status listed.)
- Pending
Links
Classifications
-
- G—PHYSICS
- G06—COMPUTING; CALCULATING OR COUNTING
- G06F—ELECTRIC DIGITAL DATA PROCESSING
- G06F8/00—Arrangements for software engineering
- G06F8/30—Creation or generation of source code
- G06F8/37—Compiler construction; Parser generation
-
- G—PHYSICS
- G06—COMPUTING; CALCULATING OR COUNTING
- G06F—ELECTRIC DIGITAL DATA PROCESSING
- G06F8/00—Arrangements for software engineering
- G06F8/40—Transformation of program code
- G06F8/41—Compilation
- G06F8/42—Syntactic analysis
- G06F8/427—Parsing
Landscapes
- Engineering & Computer Science (AREA)
- General Engineering & Computer Science (AREA)
- Theoretical Computer Science (AREA)
- Software Systems (AREA)
- Physics & Mathematics (AREA)
- General Physics & Mathematics (AREA)
- Information Transfer Between Computers (AREA)
- User Interface Of Digital Computer (AREA)
- Document Processing Apparatus (AREA)
Abstract
基于SpringMVC的API文档生成方法及系统,通过自定义的注解,在自定义数据Bean中标记API信息,所述自定义Bean用于服务端代码的Controller层的函数的出参入参,遍历服务端运行的代码Controller层方法,自动抓取其函数的入参出参引用,解析出参入参的所有参数,生成API文档,通过所述参数对象的相互引用嵌套,自动构建起API的参数层级结构,然后将其遍历解析得到的结果下发到Web客户端,为前端开发人员提供可视化的API技术文档。本发明可解决API文档更新不及时,维护成本高等问题,节约开发人员时间成本,提高工作积极性。
Description
技术领域
本发明涉及应用程序开发,具体涉及基于SpringMVC的API文档生成方法及系统。
背景技术
当前互联网中有大量的Web App开发都是使用到了JavaEE技术,并且大量地使用SpringMVC后端框架。
开发中,API文档是前后端对接接口、调试接口的必不可少的技术文档。当然API文档是独立于运行的代码之外,可以采取人工编写的方式,也可以选择网络上提供的一系列API文档生成框架生成。无论采取哪种方式,API文档的准确性、及时性极大地影响着前后端开发人员的开发效率和开发热情,所以一个高度自动化的API文档框架有着重要的意义和作用。
API接口文档如果采用Word、Excel等脱离代码的纯文本API文档,容易出现API文档版本众多,维护和发布困难,前后端代码时效性低等问题,并且极易出现人工书写错误,可靠性低。
对比现有的Apidoc的框架可以发现,其API文档描述没有脱离代码,采用Web的形式,这极大地提高API的时效性。但其API文档生成全部依赖于手写的Java注解,使得API中的关键信息(如入参出参变量名称)容易出现人工编写的错误,并且为了生成的API需要编写大量繁琐的注解,降低开发人员工作积极性。
发明内容
本发明所要解决的技术问题是针对现有技术中的不足,而提供基于SpringMVC的API文档生成方法及系统。该方法及系统可解决API文档更新不及时,维护成本高等问题,节约开发人员时间成本,提高工作积极性。
本发明公开的技术方案是:基于SpringMVC的API文档生成方法,其特征在于:通过自定义的注解,在自定义数据Bean中标记API信息,所述自定义Bean用于服务端代码的Controller层的函数参数,遍历服务端运行的代码Controller层方法,自动抓取其函数的入参出参引用,解析出参入参的所有参数,生成API文档,通过所述参数对象的相互引用嵌套,自动构建起API的参数层级结构,然后将其遍历解析得到的结果下发到Web客户端,为前端开发人员提供可视化的API技术文档。
在上述方案中,所述自定义注解由@Doc、@Act,@DataLength,@DataRange四个注解组成,用于描述API字段的属性。
在上述方案中,所述客户端展示Html页面,用于展示从服务端请求下来的API文档数据。
在上述方案中,在浏览器端由Script脚本请求服务端API文档数据,并构建Html代码,来实现向用户提供可视化API技术文档。
本发明还公开了一种技术方案:基于SpringMVC的API文档生成系统,该系统主要包括自动API文档生成框架部分和常规业务代码部分,其特征在于:
所述自动API文档生成框架部分包含:
自定义注解模块,用于标记API信息,并将其发送给常规业务代码部分的自定义数据Bean;
Doc核心解释器,用于对常规业务代码部分的SpringMVC Controller的API方法进行遍历解析,自动抓取其入参出参引用,生产生成API文档,通过所述参数对象的相互引用嵌套,自动构建起API的参数层级结构;
API视图层模块,基于Doc核心解释器所遍历解析得到的结果,将所述结果下发到Web客户端,为前端开发人员提供可视化的API技术文档;
所述常规业务代码部分包括:
自定义数据Bean,用于Controller函数的出参入参;
SpringMVC Controller,引用自定义数据Bean作为函数出参入参,作为业务代码结构进行业务运算。
在上述方案中,所述自定义注解由@Doc、@Act,@DataLength,@DataRange四个注解组成,用于描述API字段的属性。
在上述方案中,所述客户端展示包含Html页面,用于展示从服务端请求下来的API文档数据。
在上述方案中,所述API视图层模块在浏览器端由Script脚本请求服务端API文档数据,并构建Html代码,来实现向用户提供可视化API技术文档。
本发明具有如下有益的效果:
注解数量少,容易掌握,注释编写简洁,开发快速;
注解编写不涉及字段名称等关键信息,不会出现人工手写错误导致程序bug;
API的信息均是从运行的代码中抓取构建,不会出现后端修改接口的字段数量、名称、属性等信息忘了更新API描述导致的bug,时效性高;
支持无限层级嵌套,包括复杂结构(列表,对象,map)等,几乎满足所有的数据结构,并且注解的编写跟层级结构解耦,结构关系均是从运行的代码中抓取构建,在复杂的层级结构中也不会出现人为编写错误。
附图说明
图1是本发明的方法流程图;
图2是本发明的系统方框示意图。
具体实施方式
请参考图1。如图1所示,本发明所公开的基于SpringMVC的API文档生成方法主要包含以下步骤:
10. 在自定义数据Bean中标记API信息,具体为,通过自定义的注解,在自定义数据Bean中标记API信息,所述自定义Bean用于服务端代码的controller层API方法的出参入参;
11.遍历服务端Controller层方法,自动抓取其函数的入参出参引用;
12.解析出参入参的所有参数,生成API文档,通过所述参数对象的相互引用嵌套,自动构建起API的参数层级结构;
13.将其遍历解析得到的结果下发到Web客户端,为客户端提供可视化的API技术文档。
为了向客户端展示可视化API技术文档,在浏览器端由Script脚本请求服务端API文档数据,并构建Html代码,在客户端展示Html页面,来展示从服务端请求下来的API文档数据。
图2展示的为本发明的系统方框示意图。所述系统由两部分构成,分别为自动API文档生成框架部分20,以及常规业务代码部分30。
所述自动API文档生成框架部分包含:
自定义注解模块21,用于标记API信息,并将其编写(标记)在常规业务代码部分30的自定义数据Bean31;
Doc核心解释器22,用于对常规业务代码部分30的SpringMVC Controller32的API方法进行遍历解析,自动抓取其入参出参引用,生成API文档,通过所述参数对象的相互引用嵌套,自动构建起API的参数层级结构;
API视图层模块27,基于Doc核心解释器22所遍历解析得到的结果,将所述结果下发到Web客户端,为客户端提供可视化的API技术文档;
所述常规业务代码部分包括:
自定义数据Bean31,根据接收到的所述自定义注解模块21发送的内容,对API信息进行标记,Bean31作为常规业务代码,对服务端代码的Controller层进行配置;
SpringMVC Controller32,引用自定义数据Bean31作为函数出参入参,作为业务代码结构33进行业务运算。
另外,所述API视图层模块27通过由Script脚本25构建的Html代码26,来实现向用户提供可视化API技术文档。
所述API文档生成框架部分20还包括通过Servlet23配置的后端代码24,用于相关任务的执行运算;所述Servlet23主要处理web客户端向服务端获取Api文档数据的请求,Servlet是JavaEE的常规模块。
尽管已参照优选实施方式描述了本发明的技术方案,但是本领域技术人员容易理解的是,本发明的保护范围并不局限于这些具体实施方式,在不偏离本发明的基本原理的情况下,可以对所述实施方式以及其中的具体技术特征进行拆分、组合或改变,拆分、组合或改变后的技术方案仍将落入本发明的保护范围之内。
Claims (9)
1.基于SpringMVC的API文档生成方法,其特征在于:
通过自定义的注解,在自定义数据Bean中标记API信息,所述自定义Bean用于服务端代码Controller函数的出参入参;
遍历服务端运行的代码Controller层方法,自动抓取其函数的入参出参引用;
解析出参入参的所有参数,生成API文档,通过所述参数对象的相互引用嵌套,自动构建起API的参数层级结构;
将其遍历解析得到的结果下发到Web客户端,为开发人员提供可视化的API技术文档。
2.如权利要求1所述的API文档自动生成方法,其中所述自定义注解为原生的Java注解。
3.如权利要求1所述的API文档自动生成方法,其中所述自定义注解由@Doc、@Act,@DataLength,@DataRange四个注解组成,用于描述API字段的属性。
4.如权利要求1所述的API文档自动生成方法,其中所述客户端展示Html页面,用于展示从服务端请求下来的API文档数据。
5.如权利要求1所述的API文档自动生成方法,其中在服务端由Script脚本构建Html代码,来实现向用户提供可视化API技术文档。
6.基于SpringMVC的API文档生成系统,该系统主要包括自动API文档生成框架部分和常规业务代码部分,其特征在于:
所述自动API文档生成框架部分包含:
自定义注解模块,用于标记API信息,编写在常规业务代码部分的自定义数据Bean;
Doc核心解释器,用于对常规业务代码部分的SpringMVC Controller的API方法进行遍历解析,自动抓取其入参出参引用,生成API文档,通过所述参数对象的相互引用嵌套,自动构建起API的参数层级结构;
API视图层模块,基于Doc核心解释器所遍历解析得到的结果,将所述结果下发到Web客户端,为开发人员提供可视化的API技术文档;
所述常规业务代码部分包括:
自定义数据Bean,用于Controller函数的出参入参;
SpringMVC Controller,引用自定义数据Bean作为函数出参入参,作为业务代码结构进行业务运算。
7.如权利要求5所述的API文档自动生成系统,其中所述自定义注解由@Doc、@Act,@DataLength,@DataRange四个注解组成,用于描述API字段的属性。
8.如权利要求5所述的API文档自动生成系统,其中所述客户端展示Html页面,用于展示从服务端请求下来的API文档数据。
9.如权利要求5所述的API文档自动生成系统,其中所述API视图层模块通过在浏览器端由Script脚本请求服务端API文档数据,并构建Html代码,来实现向用户提供可视化API技术文档。
Priority Applications (1)
Application Number | Priority Date | Filing Date | Title |
---|---|---|---|
CN201710800995.3A CN107515771A (zh) | 2017-09-07 | 2017-09-07 | 基于SpringMVC的API文档生成方法及系统 |
Applications Claiming Priority (1)
Application Number | Priority Date | Filing Date | Title |
---|---|---|---|
CN201710800995.3A CN107515771A (zh) | 2017-09-07 | 2017-09-07 | 基于SpringMVC的API文档生成方法及系统 |
Publications (1)
Publication Number | Publication Date |
---|---|
CN107515771A true CN107515771A (zh) | 2017-12-26 |
Family
ID=60725223
Family Applications (1)
Application Number | Title | Priority Date | Filing Date |
---|---|---|---|
CN201710800995.3A Pending CN107515771A (zh) | 2017-09-07 | 2017-09-07 | 基于SpringMVC的API文档生成方法及系统 |
Country Status (1)
Country | Link |
---|---|
CN (1) | CN107515771A (zh) |
Cited By (9)
Publication number | Priority date | Publication date | Assignee | Title |
---|---|---|---|---|
CN108255513A (zh) * | 2017-12-28 | 2018-07-06 | 平安科技(深圳)有限公司 | 电子装置、基于springmvc的数据接口及其说明自动生成方法及存储介质 |
CN108415834A (zh) * | 2018-02-12 | 2018-08-17 | 平安科技(深圳)有限公司 | 注解后端校验方法、装置、计算机设备及存储介质 |
CN108804103A (zh) * | 2018-06-20 | 2018-11-13 | 郑州云海信息技术有限公司 | 一种扫描接口并生成可调用api接口文档的方法 |
CN109375901A (zh) * | 2018-09-03 | 2019-02-22 | 平安普惠企业管理有限公司 | 接口信息管理方法、装置、计算机设备以及存储介质 |
CN110704030A (zh) * | 2019-09-26 | 2020-01-17 | 北京达佳互联信息技术有限公司 | 接口配置信息生成方法、装置、电子设备及存储介质 |
CN111177240A (zh) * | 2019-12-13 | 2020-05-19 | 贝壳技术有限公司 | API数据导入方法、系统以及Mock数据生成方法 |
CN111274120A (zh) * | 2018-12-05 | 2020-06-12 | 北京奇虎科技有限公司 | 一种接口文档的验证方法和装置 |
CN111767070A (zh) * | 2020-06-30 | 2020-10-13 | 中国平安财产保险股份有限公司 | Api文档管理方法、装置、计算机设备及存储介质 |
CN113157792A (zh) * | 2021-05-10 | 2021-07-23 | 中国工商银行股份有限公司 | 一种接口文档管理系统及其工作方法 |
Citations (3)
Publication number | Priority date | Publication date | Assignee | Title |
---|---|---|---|---|
US8126901B2 (en) * | 2006-10-19 | 2012-02-28 | International Business Machines Corporation | Method and apparatus for generating a dynamic web page |
CN104182228A (zh) * | 2014-08-22 | 2014-12-03 | 徐增超 | 一种创建网络应用的方法和系统 |
CN104484216A (zh) * | 2014-12-29 | 2015-04-01 | 广州唯品会网络技术有限公司 | 服务接口文档和在线测试工具生成方法、装置 |
-
2017
- 2017-09-07 CN CN201710800995.3A patent/CN107515771A/zh active Pending
Patent Citations (3)
Publication number | Priority date | Publication date | Assignee | Title |
---|---|---|---|---|
US8126901B2 (en) * | 2006-10-19 | 2012-02-28 | International Business Machines Corporation | Method and apparatus for generating a dynamic web page |
CN104182228A (zh) * | 2014-08-22 | 2014-12-03 | 徐增超 | 一种创建网络应用的方法和系统 |
CN104484216A (zh) * | 2014-12-29 | 2015-04-01 | 广州唯品会网络技术有限公司 | 服务接口文档和在线测试工具生成方法、装置 |
Cited By (12)
Publication number | Priority date | Publication date | Assignee | Title |
---|---|---|---|---|
CN108255513A (zh) * | 2017-12-28 | 2018-07-06 | 平安科技(深圳)有限公司 | 电子装置、基于springmvc的数据接口及其说明自动生成方法及存储介质 |
WO2019127864A1 (zh) * | 2017-12-28 | 2019-07-04 | 平安科技(深圳)有限公司 | 电子装置、基于springmvc的数据接口及其说明自动生成方法及存储介质 |
CN108415834A (zh) * | 2018-02-12 | 2018-08-17 | 平安科技(深圳)有限公司 | 注解后端校验方法、装置、计算机设备及存储介质 |
CN108804103A (zh) * | 2018-06-20 | 2018-11-13 | 郑州云海信息技术有限公司 | 一种扫描接口并生成可调用api接口文档的方法 |
CN109375901A (zh) * | 2018-09-03 | 2019-02-22 | 平安普惠企业管理有限公司 | 接口信息管理方法、装置、计算机设备以及存储介质 |
CN111274120A (zh) * | 2018-12-05 | 2020-06-12 | 北京奇虎科技有限公司 | 一种接口文档的验证方法和装置 |
CN111274120B (zh) * | 2018-12-05 | 2024-02-02 | 三六零科技集团有限公司 | 一种接口文档的验证方法和装置 |
CN110704030A (zh) * | 2019-09-26 | 2020-01-17 | 北京达佳互联信息技术有限公司 | 接口配置信息生成方法、装置、电子设备及存储介质 |
CN111177240A (zh) * | 2019-12-13 | 2020-05-19 | 贝壳技术有限公司 | API数据导入方法、系统以及Mock数据生成方法 |
CN111767070A (zh) * | 2020-06-30 | 2020-10-13 | 中国平安财产保险股份有限公司 | Api文档管理方法、装置、计算机设备及存储介质 |
CN113157792A (zh) * | 2021-05-10 | 2021-07-23 | 中国工商银行股份有限公司 | 一种接口文档管理系统及其工作方法 |
CN113157792B (zh) * | 2021-05-10 | 2024-04-30 | 中国工商银行股份有限公司 | 一种接口文档管理系统及其工作方法 |
Similar Documents
Publication | Publication Date | Title |
---|---|---|
CN107515771A (zh) | 基于SpringMVC的API文档生成方法及系统 | |
CN111506310B (zh) | 生成多平台样式的方法、装置、设备及存储介质 | |
CN104484216B (zh) | 服务接口文档和在线测试工具生成方法、装置 | |
CN106484393B (zh) | 一种可视化视图设计方法 | |
CN102262534B (zh) | 基于互联网b/s结构的计算机网络游戏开发系统及方法 | |
CN105068815A (zh) | 页面编辑器交互装置和方法 | |
CN104158836A (zh) | 一种通过数据渲染移动应用界面的方法 | |
CN105447253B (zh) | 一种三维工艺数据的集成方法 | |
CN103530407B (zh) | 一种富文本文档的生成方法与装置 | |
CN107273117A (zh) | 一种编程友好型的敏捷代码自动生成系统 | |
CN102339314A (zh) | 一种基于xml的跨终端的数据表单描述与展现方法 | |
CN102662921B (zh) | 一种文档处理方法、装置和编辑器 | |
CN108228180A (zh) | 基于可视化界面设计的自动代码生成方法及系统 | |
KR101588592B1 (ko) | 객체관계 매핑 기반 하이브리드 앱 개발 시스템 및 그 방법 | |
CN108920147A (zh) | 一种Web页面构建方法、装置、计算设备和存储介质 | |
CN110750254A (zh) | 一种基于Angular的流程图编辑器实现方法 | |
CN103853737A (zh) | Html内容可视化编辑方法及系统 | |
CN104572577A (zh) | 数学公式处理方法及装置 | |
CN104050190B (zh) | 一种关系链数据处理的方法和系统、客户端 | |
CN102521008A (zh) | 程序编译装置和程序编译方法 | |
Demirli et al. | Software language engineering of architectural viewpoints | |
Guan et al. | Front-end and back-end separation-react based framework for networked remote control laboratory | |
CN105095206A (zh) | 信息处理方法以及信息处理装置 | |
CN106599087B (zh) | 一种空间信息服务的二次开发方法 | |
CN103186514A (zh) | 用于实现文档结构化的方法和装置 |
Legal Events
Date | Code | Title | Description |
---|---|---|---|
PB01 | Publication | ||
SE01 | Entry into force of request for substantive examination | ||
SE01 | Entry into force of request for substantive examination | ||
RJ01 | Rejection of invention patent application after publication |
Application publication date: 20171226 |
|
RJ01 | Rejection of invention patent application after publication |