做后端開發(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文檔效果圖：
由于參考了很多資料都沒有成功拜英，只記錄了最后成功的鏈接静汤，沒有記錄下其他的鏈接，如果您覺得其中有參考您的部分，可以留言留下您的地址虫给，我會加到參考的鏈接里的藤抡。
主要參考：
