做後端開發，自然離不開接口文檔，接口文檔不僅友善後端開發人員之間檢視，更是前端人員必要的文檔，也有可能提供給第三方來調用我們的接口。但是，寫接口文檔太費時間，而且如果沒有确定好格式，每個人寫的接口文檔可能各不相同，看起來就會很混亂。
好在
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/Swagger2Markup/spring-swagger2markup-demo
- https://blog.csdn.net/lihuaijun/article/details/79727863
- https://github.com/woshihoujinxin/swagger-gendoc