使用spring boot + swagger2markup + springFox + asciidoctor自动生成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文档效果图：

html.png

pdf.png

由于参考了很多资料都没有成功，只记录了最后成功的链接，没有记录下其他的链接，如果您觉得其中有参考您的部分，可以留言留下您的地址，我会加到参考的链接里的。

主要参考：

• https://github.com/Swagger2Markup/spring-swagger2markup-demo
• https://blog.csdn.net/lihuaijun/article/details/79727863
• https://github.com/woshihoujinxin/swagger-gendoc