CN110633102A - 一种基于微服务框架的接口文档自动生成方法及工具 - Google Patents

一种基于微服务框架的接口文档自动生成方法及工具 Download PDF

Info

Publication number
CN110633102A
CN110633102A CN201910899881.8A CN201910899881A CN110633102A CN 110633102 A CN110633102 A CN 110633102A CN 201910899881 A CN201910899881 A CN 201910899881A CN 110633102 A CN110633102 A CN 110633102A
Authority
CN
China
Prior art keywords
document
interface
micro
configuration
module
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
Application number
CN201910899881.8A
Other languages
English (en)
Inventor
王超
邵辉
王宏达
邵华
Current Assignee (The listed assignees may be inaccurate. Google has not performed a legal analysis and makes no representation or warranty as to the accuracy of the list.)
Shandong Inspur Genersoft Information Technology Co Ltd
Original Assignee
Shandong Inspur Genersoft Information Technology Co Ltd
Priority date (The priority date 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 date listed.)
Filing date
Publication date
Application filed by Shandong Inspur Genersoft Information Technology Co Ltd filed Critical Shandong Inspur Genersoft Information Technology Co Ltd
Priority to CN201910899881.8A priority Critical patent/CN110633102A/zh
Publication of CN110633102A publication Critical patent/CN110633102A/zh
Pending legal-status Critical Current

Links

Images

Classifications

    • G—PHYSICS
    • G06—COMPUTING; CALCULATING OR COUNTING
    • G06F—ELECTRIC DIGITAL DATA PROCESSING
    • G06F8/00—Arrangements for software engineering
    • G06F8/70—Software maintenance or management
    • G06F8/73—Program documentation

Landscapes

  • Engineering & Computer Science (AREA)
  • Software Systems (AREA)
  • General Engineering & Computer Science (AREA)
  • Theoretical Computer Science (AREA)
  • Library & Information Science (AREA)
  • Physics & Mathematics (AREA)
  • General Physics & Mathematics (AREA)
  • Document Processing Apparatus (AREA)
  • Stored Programmes (AREA)

Abstract

本发明公开一种基于微服务框架的接口文档自动生成方法及工具，涉及前后端开发技术领域，采用技术方案基于微服务框架，通过配置文档生成配置类、在pom.xml中配置离线文档参数、对实体bean及controller的层进行代码注解、对接口进行单端测试并最终自动生成接口文档，解决了前后端分离情况下前端人员仍需要了解后端的接口及数据格式而导致的开发效率低的问题，可满足于微服务框架前后端分离的开发模式对于接口文档的需求，既可以减少开发人员创建文档的工作量，同时将说明内容整合到实现代码中，让维护文档和修改代码整合为一体，在节省开发时间的同时，还能提高开发效率。

Description

一种基于微服务框架的接口文档自动生成方法及工具
技术领域
本发明涉及前后端分离开发的模式，具体的说是一种基于微服务框架的接口文档自动生成方法及工具。
背景技术
前后端分离开发的模式越来越流行，程序员的分工也日益明确。前端开发不需要部署后端语言的环境，后端开发也不需要前端写好的任何程序。后端只管暴露各种API接口供给前端进行数据的增、删、改、查，不负责生成HTML页面，这种方式能够减轻后端任务让后端开发更加专注。尤其是在微服务的开发框架下,前后端分离开发的模式应用更加广泛。但是前后端分离开发避免不了的是前端人员需要了解后端的接口及数据格式，如果等后端研发人员开发完成后或者开发前写好文档，则会造成一定的时间浪费。
发明内容
本发明针对目前技术发展的需求和不足之处，提供一种基于微服务框架的接口文档自动生成方法及工具，以在前后端分离开发的基础上，前端人员无需考虑后端的接口及数据格式即可进行文档的撰写，在节省开发时间的同时，还能提高开发效率。
首先，本发明提供一种基于微服务框架的接口文档自动生成方法，解决上述技术问题采用的技术方案如下：
一种基于微服务框架的接口文档自动生成方法，该方法基于微服务框架springCloud，实现步骤包括：
S10、配置文档生成配置类；
S20、在pom.xml中配置离线文档参数；
S30、对实体bean及controller的层进行代码注解；
S40、对接口进行单端测试后，使用maven命令执行单元测试以自动生成接口文档。
在步骤S10中，配置文档生成配置类，具体操作包括：
S11、定义接口文档生成的范围；
S12、定义接口文档的整体描述。
在步骤S20中，在pom.xml中配置离线文档参数时，需要：
S21、设置文档编码格式；
S22、设置文档生成路径；
S23、定义文档生成的具体格式。
在步骤S30中，依靠@ApiModel(value＝"",description＝"")，@ApiModelProperty("")，@ApiOperation("")对实体bean及controller的层进行代码注解。
其次，本发明还提供一种基于微服务框架的接口文档自动生成工具，解决上述技术问题采用的技术方案如下：
一种基于微服务框架的接口文档自动生成工具，该工具基于微服务框架springCloud，包括：
定义模块，用于配置文档生成配置类；
配置模块，用于在pom.xml中配置离线文档参数；
注解模块，用于对实体bean及controller的层进行代码注解；
测试模块，用于对接口进行单端测试；
自动生成模块，用于执行单端测试结果并自动生成接口文档。
具体的，所涉及定义模块配置文档生成配置类时，
定义模块首先定义接口文档生成的范围；
定义模块随后定义接口文档的整体描述。
具体的，所涉及配置模块在pom.xml中配置离线文档参数时，
所述配置模块首先设置文档编码格式；
所述配置模块随后设置文档生成路径；
所述配置模块最后定义文档生成的具体格式。
具体的，所涉及注解模块依靠@ApiModel(value＝"",description＝"")，@ApiModelProperty("")，@ApiOperation("")对实体bean及controller的层进行代码注解。
本发明的一种基于微服务框架的接口文档自动生成方法及工具，与现有技术相比具有的有益效果是：
1)本发明基于微服务框架，通过配置文档生成配置类、在pom.xml中配置离线文档参数、对实体bean及controller的层进行代码注解、对接口进行单端测试并最终自动生成接口文档，解决了前后端分离情况下前端人员仍需要了解后端的接口及数据格式而导致的开发效率低的问题，实现了在前后端分离开发的基础上，前端人员无需考虑后端的接口及数据格式即可进行文档的撰写，在节省开发时间的同时，还能提高开发效率；
2)本发明自动生成的接口文档可满足于微服务框架前后端分离的开发模式对于接口文档的需求，既可以减少开发人员创建文档的工作量，同时将说明内容整合到实现代码中，让维护文档和修改代码整合为一体，可以让开发人员在修改代码逻辑的同时方便的修改文档说明，开发人员不必专门再编制接口文档，极大提高了开发效率。
附图说明
附图1是本发明实施例一的方法流程图；
附图2是本发明实施例二的连接框图。
附图中各标号信息表示：
1、定义模块，2、配置模块，3、注解模块，
4、测试模块，5、自动生成模块。
具体实施方式
为使本发明的技术方案、解决的技术问题和技术效果更加清楚明白，以下结合具体实施例，对本发明的技术方案进行清楚、完整的描述，显然，所描述的实施例仅仅是本发明的一部分实施例，而不是全部的实施例。
实施例一：
结合附图1，本实施例提出一种基于微服务框架的接口文档自动生成方法，该方法基于微服务框架springCloud，实现步骤包括：
S10、配置文档生成配置类。
在步骤S10中，配置文档生成配置类，具体操作包括：
S11、定义接口文档生成的范围，即定义：
Docket(DocumentationType.SWAGGER_2).apis(RequestHandlerSelectors.basePackage(""))
S12、定义接口文档的整体描述，即定义：
Docket(DocumentationType.SWAGGER_2).description(“”)
其中，basePackage("")是指swagger要扫描的API包，.title("")为API接口文档的标题，.description(“”)是对该文档的描述,.contact是指联系人，.version(“”)是指版本。
步骤S10的具体执行代码为：
Figure BDA0002211487340000041
S20、在pom.xml中配置离线文档参数。
在步骤S20中，在pom.xml中配置离线文档参数时，需要：
S21、设置文档编码格式，执行的代码命令为：
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
其中，文档构建后，编码格式为UTF-8。
S22、设置文档生成路径，执行的代码命令为：
<asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
S23、定义文档生成的具体格式，执行以下2种文档格式的代码命令为：
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory》
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
基于步骤S21-S23，在pom.xml中配置离线文档参数，其具体执行代码为：
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
<asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
<generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
</properties>
S30、对实体bean及controller的层进行代码注解。
在步骤S30中，依靠@ApiModel(value＝"",description＝"")，@ApiModelProperty("")，@ApiOperation("")对实体bean及controller的层进行代码注解。
步骤S30的具体执行代码为：
Figure BDA0002211487340000061
S40、对接口进行单端测试，该步骤的执行代码为：
Figure BDA0002211487340000062
最后，基于上述执行代码，使用maven命令执行单元测试以自动生成接口文档。
实施例二：
结合附图2，本实施例提出一种基于微服务框架的接口文档自动生成工具，该工具基于微服务框架springCloud，包括：
定义模块1，用于配置文档生成配置类；
配置模块2，用于在pom.xml中配置离线文档参数；
注解模块3，用于对实体bean及controller的层进行代码注解；
测试模块4，用于对接口进行单端测试；
自动生成模块5，用于执行单端测试结果并自动生成接口文档。
在本实施例中，所涉及定义模块1配置文档生成配置类时，具体执行代码为：
Figure BDA0002211487340000071
Figure BDA0002211487340000081
定义模块1配置文档生成配置类时，定义模块1定义接口文档生成的范围，该过程的执行代码为：
Docket(DocumentationType.SWAGGER_2).apis(RequestHandlerSelectors.basePackage(""))
定义模块1定义接口文档的整体描述，该过程的执行代码为：
Docket(DocumentationType.SWAGGER_2).description(“”)
其中，basePackage("")是指swagger要扫描的API包，.title("")为API接口文档的标题，.description(“”)是对该文档的描述,.contact是指联系人，.version(“”)是指版本。
在本实施例中，所涉及配置模块2在pom.xml中配置离线文档参数的具体执行代码为：
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
<asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
<generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
</properties>
其中，
所涉及配置模块2设置文档编码格式，具体执行的代码为：
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
文档构建后，编码格式为UTF-8；
所涉及配置模块2设置文档生成路径，具体执行的代码为：
<asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
所涉及配置模块2定义文档生成的具体格式，定义以下2中文档格式时执行的代码为：
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory》
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
在本实施例中，所涉及注解模块3依靠@ApiModel(value＝"",description＝"")，@ApiModelProperty("")，@ApiOperation("")对实体bean及controller的层进行代码注解。
所涉及注解模块3对实体bean及controller的层进行代码注解，具体的执行代码为：
Figure BDA0002211487340000101
所涉及测试模块4对接口进行单端测试的执行代码为：
Figure BDA0002211487340000102
基于测试模块4执行上述代码后，所涉及自动生成模块5使用maven命令执行单元测试以自动生成接口文档。
综上可知，采用本发明的一种基于微服务框架的接口文档自动生成方法及工具，可满足于微服务框架前后端分离的开发模式对于接口文档的需求，既可以减少开发人员创建文档的工作量，同时将说明内容整合到实现代码中，让维护文档和修改代码整合为一体，可以让开发人员在修改代码逻辑的同时方便的修改文档说明，开发人员不必专门再编制接口文档，极大提高了开发效率，解决了前后端分离情况下前端人员仍需要了解后端的接口及数据格式而导致的开发效率低的问题。
以上应用具体个例对本发明的原理及实施方式进行了详细阐述，这些实施例只是用于帮助理解本发明的核心技术内容，并不用于限制本发明的保护范围，本发明的技术方案不限制于上述具体实施方式内。基于本发明的上述具体实施例，本技术领域的技术人员在不脱离本发明原理的前提下，对本发明所作出的任何改进和修饰，皆应落入本发明的专利保护范围。

Claims (8)

1.一种基于微服务框架的接口文档自动生成方法，其特征在于,该方法基于微服务框架springCloud，实现步骤包括：
S10、配置文档生成配置类；
S20、在pom.xml中配置离线文档参数；
S30、对实体bean及controller的层进行代码注解；
S40、对接口进行单端测试后，使用maven命令执行单元测试以自动生成接口文档。
2.根据权利要求1所述的一种基于微服务框架的接口文档自动生成方法，其特征在于，在步骤S10中，配置文档生成配置类，具体操作包括：
S11、定义接口文档生成的范围；
S12、定义接口文档的整体描述。
3.根据权利要求2所述的一种基于微服务框架的接口文档自动生成方法，其特征在于，在步骤S20中，在pom.xml中配置离线文档参数时，需要：
S21、设置文档编码格式；
S22、设置文档生成路径；
S23、定义文档生成的具体格式。
4.根据权利要求3所述的一种基于微服务框架的接口文档自动生成方法，其特征在于，在步骤S30中，依靠@ApiModel(value＝"",description＝"")，@ApiModelProperty("")，@ApiOperation("")对实体bean及controller的层进行代码注解。
5.一种基于微服务框架的接口文档自动生成工具，其特征在于,该工具基于微服务框架springCloud，包括：
定义模块，用于配置文档生成配置类；
配置模块，用于在pom.xml中配置离线文档参数；
注解模块，用于对实体bean及controller的层进行代码注解；
测试模块，用于对接口进行单端测试；
自动生成模块，用于执行单端测试结果并自动生成接口文档。
6.根据权利要求5所述的一种基于微服务框架的接口文档自动生成工具，其特征在于，所述定义模块配置文档生成配置类时，
定义模块首先定义接口文档生成的范围；
定义模块随后定义接口文档的整体描述。
7.根据权利要求5所述的一种基于微服务框架的接口文档自动生成工具，其特征在于，所述配置模块在pom.xml中配置离线文档参数时，
所述配置模块首先设置文档编码格式；
所述配置模块随后设置文档生成路径；
所述配置模块最后定义文档生成的具体格式。
8.根据权利要求5所述的一种基于微服务框架的接口文档自动生成工具，其特征在于，所述注解模块依靠@ApiModel(value＝"",description＝"")，@ApiModelProperty("")，@ApiOperation("")对实体bean及controller的层进行代码注解。
CN201910899881.8A 2019-09-23 2019-09-23 一种基于微服务框架的接口文档自动生成方法及工具 Pending CN110633102A (zh)

Priority Applications (1)

Application Number Priority Date Filing Date Title
CN201910899881.8A CN110633102A (zh) 2019-09-23 2019-09-23 一种基于微服务框架的接口文档自动生成方法及工具

Applications Claiming Priority (1)

Application Number Priority Date Filing Date Title
CN201910899881.8A CN110633102A (zh) 2019-09-23 2019-09-23 一种基于微服务框架的接口文档自动生成方法及工具

Publications (1)

Publication Number Publication Date
CN110633102A true CN110633102A (zh) 2019-12-31

Family

ID=68972341

Family Applications (1)

Application Number Title Priority Date Filing Date
CN201910899881.8A Pending CN110633102A (zh) 2019-09-23 2019-09-23 一种基于微服务框架的接口文档自动生成方法及工具

Country Status (1)

Country Link
CN (1) CN110633102A (zh)

Cited By (3)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN111611173A (zh) * 2020-05-27 2020-09-01 中航信移动科技有限公司 一种应用于微服务工程接口文档检测的系统和方法
CN114443129A (zh) * 2021-12-30 2022-05-06 广东南方新媒体科技有限公司 一种项目文档自动化生成方法、设备及存储介质
CN115809089A (zh) * 2023-01-12 2023-03-17 深圳市银云信息技术有限公司 一种基于文档和测试驱动开发的方法

Citations (2)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN103049271A (zh) * 2012-12-27 2013-04-17 微梦创科网络科技（中国）有限公司 自动生成api接口的描述文档的方法和装置
CN107256160A (zh) * 2017-06-12 2017-10-17 郑州云海信息技术有限公司 一种持续集成中的代码文档生成方法、装置及系统

Patent Citations (2)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN103049271A (zh) * 2012-12-27 2013-04-17 微梦创科网络科技（中国）有限公司 自动生成api接口的描述文档的方法和装置
CN107256160A (zh) * 2017-06-12 2017-10-17 郑州云海信息技术有限公司 一种持续集成中的代码文档生成方法、装置及系统

Non-Patent Citations (2)

* Cited by examiner, † Cited by third party
Title
GARYOND: "Spring Boot集成Swagger 2实现API接口文档管理", 《HTTPS://WWW.JIANSHU.COM/P/64C2947E1F48》 *
南下玩技术笔记: "Swagger自动生成接口文档", 《HTTPS://WWW.CNBLOGS.COM/NODEGIS/P/10072709.HTML》 *

Cited By (4)

* Cited by examiner, † Cited by third party
Publication number Priority date Publication date Assignee Title
CN111611173A (zh) * 2020-05-27 2020-09-01 中航信移动科技有限公司 一种应用于微服务工程接口文档检测的系统和方法
CN114443129A (zh) * 2021-12-30 2022-05-06 广东南方新媒体科技有限公司 一种项目文档自动化生成方法、设备及存储介质
CN115809089A (zh) * 2023-01-12 2023-03-17 深圳市银云信息技术有限公司 一种基于文档和测试驱动开发的方法
CN115809089B (zh) * 2023-01-12 2023-08-15 深圳市银云信息技术有限公司 一种基于文档和测试驱动开发的方法

Similar Documents

Publication Publication Date Title
CN110633102A (zh) 一种基于微服务框架的接口文档自动生成方法及工具
CN102929682B (zh) 自动扩展tcl语言的预处理方法和装置
CN104133772A (zh) 一种自动生成测试数据的方法
CN104778124A (zh) 一种软件应用自动化测试方法
CN101645010A (zh) 代码自动生成系统及方法
CN110109671B (zh) 一种webpack标签尺寸样式转换方法及装置
CN109783195A (zh) 一种基于容器的智能合约实时调试方法
CN102841841A (zh) 一种测试中的断言处理方法及系统
US11288062B2 (en) Automatic source code refactoring
CN111427583A (zh) 组件的编译方法、装置和电子设备及计算机可读存储介质
CN105068812A (zh) 一种表单生成方法及装置
CN110908894A (zh) 一种基于vuex的可视化报表工具自动化测试方法及装置
CN102455903B (zh) 一种用户应用界面的生成方法
CN116931911A (zh) 一种基于aigc的智能低代码应用开发平台及开发方法
CN103077038B (zh) 动态生成和编译.net项目的方法
CN111124380A (zh) 一种前端代码生成方法
CN109522005A (zh) 跨平台图形化程序设计方法
CN104102581A (zh) 一种实现单元测试的方法及装置
CN101604286A (zh) 一种关键字驱动表格生成方法
CN105138337A (zh) 一种插件适配方法及插件适配装置
CN106919374B (zh) 一种脚本生成方法和装置
CN114047970A (zh) 一种autosar架构软件的配置方法及系统
CN106383734A (zh) 一种从代码中提取详细设计的方法
CN113655996A (zh) 一种基于需求模型的企业级系统生成方法
CN103500109A (zh) 一种用于实现文件收集、软件包自动安装的方法及装置

Legal Events

Date Code Title Description
PB01 Publication
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
RJ01 Rejection of invention patent application after publication

Application publication date: 20191231