使用spring boot + swagger自動生成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文檔效果圖：

因爲參考了不少資料都沒有成功，只記錄了最後成功的連接，沒有記錄下其餘的連接，若是您以爲其中有參考您的部分，能夠留言留下您的地址，我會加到參考的連接裏的。

主要參考：

• https://github.com/Swagger2Ma...
• https://blog.csdn.net/lihuaij...
• https://github.com/woshihouji...