swagger生成离线文档记录（支持中文）

本档中的附件需要到有道云笔记的分享中下载：

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`，只要控制台显示成功，在当前项目的`target\asciidoc\html`和`target\asciidoc\pdf`分别存放着`HTML文档`和`PDF文档`。

 

> 注意：其他IDE工具没有试过，如需使用，请自行研究。

 

# 其他说明

 

为了本项目使用方便，不建议将要生成文档的项目源码整合到本项目，这样做比较麻烦，需要每个项目都加。

 

比较好的做法是：

 

- 首先你的项目要确保是`spring boot`的，并且集成了`swagger`，接口层和入参出参实体类加了`swagger`的相关注解，且能正确跑起来；

- 然后将本项目的`src/test/java`下`com.example.swagger2pdf`中的`Swagger2PdfTest`类中的注释放开，将生成当前项目的`swagger.json`的代码注释掉，将`url`中的`ip`和`port`换成自己要生成文档的项目的`ip`和`port`，这里要确保这个`url`直接访问有数据返回，不然是无法生成文档的；

- 最后按上面说的运行项目即可生成文档。