做后端開發(fā)，自然離不開接口文檔，接口文檔不僅方便后端開發(fā)人員之間查看，更是前端人員必要的文檔，也有可能提供給第三方來調(diào)用我們的接口。但是，寫接口文檔太費時間，而且如果沒有確定好格式，每個人寫的接口文檔可能各不相同，看起來就會很混亂。
好在swagger出現(xiàn)了，如果你的spring boot項目集成了swagger，而且接口和入?yún)⒊鰠嶓w類加上了swagger相關(guān)的注解(參考最終demo中的controller和model)，那么，就可以通過http://ip:port/swagger-ui.html(ip和port換成自己配置的)來訪問在線的接口，在此頁面也可以直接測試接口。對spring boot和swagger不了解的建議先學(xué)習(xí)一下，近年來很火，使用起來也確實方便。但是我們肯定不會滿足在線訪問就可以了的，有時候會需要離線的接口文檔，于是就有了swagger2markup、springFox、asciidoctor幾個插件來幫助我們生成離線的HTML和PDF格式的文檔。
關(guān)于使用swagger生成HTML或者PDF的原理，可以參考這篇文章：使用 SpringFox、Swagger2Markup、Spring-Restdoc和 Maven 構(gòu)建 RESTful API文檔。
首先是從spring-swagger2markup-demo下載了demo，這個demo已經(jīng)能夠生成HTML和PDF文檔了，但是對中文支持不好，中文大部分會顯示為空白。如果你的接口文檔是全英文的，那么就用這個就可以了。關(guān)于這個demo對中文支持不好，查了很多資料，應(yīng)該是字體和主題的原因，所以參考了很多資料，結(jié)合當(dāng)前這個demo，做出了最終的能很好支持中文的demo，最終demo地址：swagger2pdf。
生成的文檔存放的目錄：當(dāng)前項目的target\asciidoc\html和target\asciidoc\pdf分別存放著HTML文檔和PDF文檔。
關(guān)于接口和入?yún)⒊鰠嶓w類中用到的swagger注解，可以參考這篇博客：swagger2常用注解說明。
最終生成的HTML文檔和PDF文檔效果圖：
由于參考了很多資料都沒有成功，只記錄了最后成功的鏈接，沒有記錄下其他的鏈接，如果您覺得其中有參考您的部分，可以留言留下您的地址，我會加到參考的鏈接里的。
主要參考：
