共计 1063 个字符，预计需要花费 3 分钟才能阅读完成。
做后端开发，自然离不开接口文档，接口文档不仅方便后端开发人员之间查看，更是前端人员必要的文档，也有可能提供给第三方来调用我们的接口。但是，写接口文档太费时间，而且如果没有确定好格式，每个人写的接口文档可能各不相同，看起来就会很混乱。
好在 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…
