使用spring boot + swagger自动生成HTML、PDF接口文档，并解决中文显示为空白问题

作后端开发，天然离不开接口文档，接口文档不只方便后端开发人员之间查看，更是前端人员必要的文档，也有可能提供给第三方来调用咱们的接口。可是，写接口文档太费时间，并且若是没有肯定好格式，每一个人写的接口文档可能各不相同，看起来就会很混乱。

好在swagger出现了，若是你的spring boot项目集成了swagger，并且接口和入参出参实体类加上了swagger相关的注解(参考最终demo中的controller和model)，那么，就能够经过http://ip:port/swagger-ui.html(ip和port换成本身配置的)来访问在线的接口，在此页面也能够直接测试接口。对spring boot和swagger不了解的建议先学习一下，近年来很火，使用起来也确实方便。可是咱们确定不会知足在线访问就能够了的，有时候会须要离线的接口文档，因而就有了swagger2markup、springFox、asciidoctor几个插件来帮助咱们生成离线的HTML和PDF格式的文档。

关于使用swagger生成HTML或者PDF的原理，能够参考这篇文章：使用 SpringFox、Swagger2Markup、Spring-Restdoc和 Maven 构建 RESTful API文档。

首先是从spring-swagger2markup-demo下载了demo，这个demo已经可以生成HTML和PDF文档了，可是对中文支持很差，中文大部分会显示为空白。若是你的接口文档是全英文的，那么就用这个就能够了。关于这个demo对中文支持很差，查了不少资料，应该是字体和主题的缘由，因此参考了不少资料，结合当前这个demo，作出了最终的能很好支持中文的demo，最终demo地址：swagger2pdf。

生成的文档存放的目录：当前项目的target\asciidoc\html和target\asciidoc\pdf分别存放着HTML文档和PDF文档。

关于接口和入参出参实体类中用到的swagger注解，能够参考这篇博客：swagger2经常使用注解说明。

最终生成的HTML文档和PDF文档效果图：

因为参考了不少资料都没有成功，只记录了最后成功的连接，没有记录下其余的连接，若是您以为其中有参考您的部分，能够留言留下您的地址，我会加到参考的连接里的。

主要参考：

• https://github.com/Swagger2Ma...
• https://blog.csdn.net/lihuaij...
• https://github.com/woshihouji...