swagger导出excel文档_将Swagger2文档导出为HTML或markdown等格式离线阅读
网上有很多《使用swagger2构建API文档》的文章,该文档是一个在线文档,需要使用HTTP访问。但是在我们日常使用swagger接口文档的时候,有的时候需要接口文档离线访问,如将文档导出为html、markdown格式。又或者我们不希望应用系统与swagger接口文档使用同一个服务,而是导出HTML之后单独部署,这样做保证了对接口文档的访问不影响业务系统,也一定程度提高了接口文档的安全性。核心的实现过程就是:
在swagger2接口文档所在的应用内,利用swagger2markup将接口文档导出为adoc文件,也可以导出markdown文件。
然后将adoc文件转换为静态的html格式,可以将html发布到nginx或者其他的web应用容器,提供访问(本文不会讲html静态部署,只讲HTML导出)。
注意:adoc是一种文件格式,不是我的笔误。不是doc文件也不是docx文件。
一、maven依赖类库
在已经集成了swagger2的应用内,通过maven坐标引入相关依赖类库,pom.xml代码如下:
io.github.swagger2markup
swagger2markup
1.3.1
io.swagger
swagger-core
1.5.16
io.swagger
swagger-models
1.5.16
swagger2markup用于将swagger2在线接口文档导出为html,markdown,adoc等格式文档,用于静态部署或离线阅读。其中第一个maven坐标是必须的。后两个maven坐标,当你在执行后面的代码过程中报下图中的ERROR,或者有的类无法import的时候使用。
产生异常的原因已经有人在github的issues上给出解释了:当你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就会有异常发生。所以我们显式的引入这两个jar,替换掉swagger2默认引入的这两个jar。
二、生成adoc格式文件
下面的代码是通过编码方式实现的生成adoc格式文件的方式
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
@Test
public void generateAsciiDocs() throws Exception {
// 输出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC) //设置生成格式
.withOutputLanguage(Language.ZH) //设置语言中文还是其他语言
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("src/main/resources/docs/asciidoc"));
}
}
使用RunWith注解和SpringBootTest注解,启动应用服务容器。 SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定义的端口,而不是随机使用一个端口进行测试,这很重要。
Swagger2MarkupConfig 是输出文件的配置,如文件的格式和文件中的自然语言等
Swagger2MarkupConverter的from表示哪一个HTTP服务作为资源导出的源头(JSON格式),可以自己访问试一下这个链接。8888是我的服务端口,需要根据你自己的应用配置修改。
toFile表示将导出文件存放的位置,不用加后缀名。也可以使用toFolder表示文件导出存放的路径。二者区别在于使用toFolder导出为文件目录下按标签TAGS分类的多个文件,使用toFile是导出一个文件(toFolder多个文件的合集)。
@Test
public void generateMarkdownDocsToFile() throws Exception {
// 输出Markdown到单文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("src/main/resources/docs/markdown"));
}
上面的这一段代码是生成markdown格式接口文件的代码。执行上面的2段单元测试代码,就可以生产对应格式的接口文件。
还有一种方式是通过maven插件的方式,生成adoc和markdown格式的接口文件。笔者不常使用这种方式,没有使用代码生成的方式配置灵活,很多配置都放到pom.xml感觉很臃肿。但还是介绍一下,首先配置maven插件swagger2markup-maven-plugin。
io.github.swagger2markup
swagger2markup-maven-plugin
1.3.1
http://localhost:8888/v2/api-docs
src/main/resources/docs/asciidoc
ASCIIDOC
然后运行插件就可以了,如下图:
三、通过maven插件生成HTML文档
org.asciidoctor
asciidoctor-maven-plugin
1.5.6
src/main/resources/docs
src/main/resources/html
html
coderay
left
true
adoc的sourceDirectory路径必须和第三小节中生成的adoc文件路径一致。然后按照下图方式运行插件。
HTMl接口文档显示的效果如下,有了HTML接口文档你想转成其他各种格式的文档就太方便了,有很多工具可以使用。这里就不一一介绍了。
期待您的关注
本文转载注明出处(必须带连接,不能只转文字):字母哥博客。
swagger导出excel文档_将Swagger2文档导出为HTML或markdown等格式离线阅读相关推荐
- markdown引入代码_将Swagger2文档导出为HTML或markdown等格式离线阅读
网上有很多<使用swagger2构建API文档>的文章,该文档是一个在线文档,需要使用HTTP访问.但是在我们日常使用swagger接口文档的时候,有的时候需要接口文档离线访问,如将文档导 ...
- html文档生成pdf离线文件,将Swagger2文档导出为HTML或markdown等格式离线阅读解析.pdf...
将将Swagger2文文档档导导出出为为HTML或或markdown等等格格式式离离线线阅阅读读解解析析 网上有很多 <使用swagger2构建A PI文档>的文章,该文档 一个在线文档, ...
- html table导出excel 插入图片_前端 Table 用 JS 导出EXCEL(支持大量数据,保留报表格式) - pensive2019...
最近项目上,需要用到将网页上的table报表导出Excel.原先一直用,面对简单的数结构时只要简单的套用就能导出了,但是table结构相对复杂时,很难在组成一样结构,要花很多时间调:这时就想到在百度上 ...
- 前端自己导出excel表格 不需要调接口(可导出全部的数据)
前端自己导出excel表格 不需要调接口(可导出全部的数据) 1.下载 npm install -S file-saver xlsx 2.把js放在对应的位置 全部复制(Export2Excel.js ...
- bootstraptable导出excel独立使用_使用 EasyPOI 优雅导出Excel模板数据(含图片)
EasyPOI功能如同名字Easy,主打的功能就是容易,让一个没接触过POI的人员可以方便的写出Excel导出,Excel模板导出,Excel导入,Word模板导出.通过简单的注解和模板语言(熟悉的表 ...
- java api文档_细说API – 文档和前后端协作
在上一篇文章--<细说API – 重新认识RESTful>中介绍了如何理解和设计RESTful风格的API,现在我们来聊聊如何有效的呈现API文档,以及前后端协作的方式. 我经历过一些没有 ...
- python用二维码共享文档_[源码和文档分享]基于Python的QR二维码的生成与识别程序...
摘 要 进入二十一世纪之后,高新技术产业得到了极其迅速的发展.计算机.互联网.物联网.云计算等领域的发展,使得整个社会的信息化程度极大提高.随着技术的不断成熟,目前的一维条形码已逐渐向二维码过渡.本课 ...
- flowable 中文文档_取出word文档文字内容生成加了目录、标号和页码的PDF文件
word文档内的一页: 将文本取出来,生成自定义格式的PDF文件: 从word取出文本时标题的标号和页码是取不出来的,要自己加.另外就是目录也要自己生成和添加: 代码和解释如下: from repor ...
- java将jsp页面表格导出excel表格数据_简单的POI导出JSP页面表格数据到excel
数据库中的equipment表数据: 读取数据库中表数据的代码TestExcel.java public class TestExcel extends BaseAction{/** * @param ...
最新文章
- python使用matplotlib可视化间断条形图、使用broken_barh函数可视化间断条形图、可视化定性数据的相同指标在时间维度上的差异
- 深度解析机器学习中的置信区间(附代码)
- 一个封锁操作被对 wsacancelblockingcall 的调用中断_操作系统概论
- 11旋转编码器原理_旋转编码器的原理是什么?增量式编码器和绝对式编码器有什么区别?...
- ASP.NET报错集合一----.net4.0创建项目后,在iis上部署项目,无法浏览,提示404
- python_10_文件操作
- 组装生成HashMap结构类型
- 6月国产网络游戏审批信息公布 共计86款游戏过审
- 前台JS事件与服务器事件的执行顺序
- 海底捞、百果园、大娘水饺凭什么可以疯狂扩张门店?
- taobao-pamirs-schedule-2.0源码分析——任务队列分配源码分析
- sql字段合并mysql_sql合并字段
- Jeff Dean 的传奇人生:超级工程师们拯救谷歌
- android+设置运行内存大小,怎样增大安卓手机的虚拟运行内存RAM ,手机的ram太小....
- 网站启用CDN加速对百度SEO排名有什么影响?
- Python将npy文件转换为mat文件
- 10g recyclebin与用户表空间限额
- 适合学生党无线蓝牙耳机,好用又实惠蓝牙耳机推荐
- uni-app如何自定义内容生成二维码?
- mysql不等于null和等于null的写法
热门文章
- OpenCv3 VideoCapture读取视频失败解决方法
- win10安装oracle 11g最新亲身经历操作记录
- C++ 模板详解(一)
- 从一段代码的汇编看计算机的工作原理
- ACE反应器(Reactor)模式
- GetCurrentDirectory()函数误区
- 静态路由实验 +http+dns_华为静态路由配置实验
- 计算机网络实验报告哈工大_哈工大计算机网络实验报告.doc
- js 按钮(checkbox)控制多个checkbox的选中或不选中问题
- 树莓派GPIO的两种模式区别