本檔中的附件需要到有道雲筆記的分享中下載：
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`直接訪問有數據返回，不然是無法生成文檔的；
- 最后按上面說的運行項目即可生成文檔。