swagger通过swagger2markup导出PDF和HTML文档
本文由个人总结,如需转载使用请标明原著及原文地址
写这篇文章的主要原因是,我以前写了篇spring-boot整合swagger的文章,我文章中没有提到任何导出相关的部分,毕竟我工作中没那个需求,我自己一人写vue+spring-boot的项目,实际上连swagger都没怎么用到。
但是,但是说的才是重点,可能百度搜索的关键词在CSDN里的文章推荐里出现,导致很多人跑到我那篇文章,没看标题没看内容就留言什么“导出呢?导出呢?” “逐渐忘掉标题...” →_→ 我是很无语,好吧虽然对我没啥用,还是为键盘侠们去找个swagger导出给你们吧,这次是有“导出”两个字了,里面的坑我也基本都挖过一遍了
希望大家有时间多自己动手做做,像这个框架的坑,纯百度也才半天就能全整完,有时间的话,可以自己做做技术的整合,对你走在程序员的道路上会有很大帮助
本文主要讲通过swagger2markup导出pdf和html文档
对于不看标题的孩子们我也为你们准备了导出word文档的地址 叫爸爸 和 demo 再叫一声,左边两个神奇的字符是超链接,请自行看大佬们的文档,自行填坑,我个人比较讨厌10种人,一种是不看标题的,一种是看不懂中文的中国人,所以超链接才写的那么个性
先上个效果图
1.下载Swagger2Markup Demo
git地址:Swagger2Markup Demo (我也不知道是不是官方的,如果不是留言下,毕竟大佬们做个框架不容易)
这是下载下来的基础目录,关于gradle可以不用管,有兴趣可以自行了解,我稍微查了下,应该是和maven一样的依赖仓库管理软件,正常我们java都用maven的吧
2.导入依赖
<dependencis>部分大多在默认的maven仓库中就能下载的到
除了ch.netzwerg.paleo-core和<plugin>里的包是由https://repo.spring.io/libs-milestone管理的
2.1所以给你2种办法一种
是在maven的conf的setting里加<mirror>,因为这里我不是用这种方法,所以就给个截图你们自己填上去了
2.2另一种是在maven中加repositories
<repositories>
<repository>
<id>jcentral</id>
<name>bintray</name>
<url>https://repo.spring.io/libs-milestone</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
<checksumPolicy>fail</checksumPolicy>
</snapshots>
</repository>
</repositories>
<repositories> 和 <dependencis>平级
╮(╯▽╰)╭ 不知道你们能不能下,反正我是这样下载下来了,不行就去配<mirror>镜像,不会问度娘
3.执行命令生成pdf和html
依赖都下好,pom.xml里没有报错后,使用mvn clean test命令,项目会自动打包
直接到spring-swagger2markup-demo项目目录下用cmd执行命令就行
如果提示mvn不是内部外部命令配置下maven的环境变量就好
如果说java compile ... jre rather than jdk 那么配置下环境变量 JAVA_HOME
4.中文丢失问题解决
asciidoctor作者大大好像不是中国人,所以这个框架导出的pdf和html大部分中文会显示空白
原因在于asciidoctor的默认生成字体不支持中文,所以中文显示空白
╮(╯▽╰)╭ 所以我们可以把自己的字体强行塞进去,让她生出我们中国的孩子
如果你实在懒得动手,那就下载吧,我个人还是支持多动手asciidoctorj-pdf-1.5.0下载
4.1把字体放入压缩包
先找到asciidoctor的jar包
maven仓库路径\repository\org\asciidoctor\asciidoctorj-pdf\1.5.0-alpha.16
路径和版本可能和我的不一样,自己对应更换
然后用压缩文件打开jar包
asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\fonts
4.2修改asciidoctor的配置文件
同样用压缩软件打开刚才那个jar包,目录转到
asciidoctorj-pdf-1.5.0-alpha.16.jar\gems\asciidoctor-pdf-1.5.0.alpha.16\data\themes
用记事本打开default-theme.yml
更换font -> catalog -> Noto Serif 里的四个字体,和你之前放在data目录下的字体文件名一致
然后压缩文件会问“default-theme.yml内容改变了,是否更新到压缩文件中” →_→ 当然选是了 不然你打开这个文件是开着玩的
然后回到spring-swagger2markup-demo项目目录下用cmd执行命令
mvn asciidoctor:process-asciidoc
mvn generate-resources
执行成功后再次执行mvn clean test 就可以得到支持中文的pdf和html文件了~~~~
建议大家多动动手,这样才能在秃头的路上渐行渐远,都拿现成的东西来用,你就失去了程序员的价值了,这句话主要留给某些键盘侠
参考文献
1.https://blog.csdn.net/gongxsh00/article/details/80508963
2.https://blog.csdn.net/qq_29534483/article/details/81235081