本档中的附件需要到有道云笔记的分享中下载：
https://note.youdao.com/ynoteshare1/index.html?id=78031789325c5a5a9926818bbfe9a22e&type=note
一、IDE为idea，使用maven构建的spring-boot工程，swagger版本为2.7.0
二、拷贝docs目录、fonts目录与themes目录到src目录下，fonts与themes是解决中文字体丢失的关键
三、拷贝测试类到test目录下，注意测试类的包路径与项目启动类的包路径一致，否则需要手动指定
四、修改pom.xml，加入文档需要的依赖与插件配置，以下为参考的pom：
五、运行mvn test
六、查看生成的文档，如果想要word文档，需要用转换工具进行转换
以下为文档效果：
七、过程中遇到的问题：
1. 单元测试类与项目启动类包路径不一致，导致无法运行单元测试
2. 添加loback.xml后无法加载，改为logback-spring后可以，在参考的demo中无此问题
3. <skipTests>true</skipTests> 要改为false或者注释掉
4. 其他各种小问题，这个文档是测试成功后整理的，未全部记录
5. 如果有做接口分组，需要指定组名称
MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs? group=open-api")
.accept(MediaType.APPLICATION_JSON))
.andExpect(status().isOk())
.andReturn();
八、生产环境使用建议：
1. 整理了个用于生产环境生成离线文档的模板项目，比如本文档中的附件
2. 复制一份用于生成文档的工程
3. 参考本文档，生成接口离线文档（pdf/html），如果不需要生成所有接口的文档，则在swagger的配置类中指定
4. 文档生成后，确认正确即可删除此次的使用的工程
附录：
能正确运行的案例：
# swagger2pdf
使用springBoot + springFox + swagger2markup + asciidoctorj-pdf，生成HTML和PDF格式的接口文档，也解决了PDF文档中文显示为空白的问题。
关于本项目的一些其他信息，可以看我的[这篇博客](https://blog.csdn.net/u013719669/article/details/80998225)。
# 实现原理：
1. 先利用`SpringFox`库生成`RESTful API`
2. 再利用`Swagger2Markup` Maven插件生成`asciidoc`文档
3. 最后利用`asciidoctor` Maven插件生成 html 或 pdf 文件
# 如何使用本项目
先下载本项目到本地，导入`eclipse`，等待`maven`下载完依赖的`jar包`，即可使用。运行时只需要在项目上右击-->`Run As`-->`Maven clean`-->在项目上右击-->`Run As`-->`Maven test`，只要控制台显示成功，在当前项目的`targetasciidochtml`和`targetasciidocpdf`分别存放着`HTML文档`和`PDF文档`。
> 注意：其他IDE工具没有试过，如需使用，请自行研究。
# 其他说明
为了本项目使用方便，不建议将要生成文档的项目源码整合到本项目，这样做比较麻烦，需要每个项目都加。
比较好的做法是：
- 首先你的项目要确保是`spring boot`的，并且集成了`swagger`，接口层和入参出参实体类加了`swagger`的相关注解，且能正确跑起来；
- 然后将本项目的`src/test/java`下`com.example.swagger2pdf`中的`Swagger2PdfTest`类中的注释放开，将生成当前项目的`swagger.json`的代码注释掉，将`url`中的`ip`和`port`换成自己要生成文档的项目的`ip`和`port`，这里要确保这个`url`直接访问有数据返回，不然是无法生成文档的；
- 最后按上面说的运行项目即可生成文档。