將Swagger2文檔導(dǎo)出為HTML或markdown等格式離線閱讀
網(wǎng)上有很多《使用swagger2構(gòu)建API文檔》的文章鳖目，swagger2文檔是一個在線文檔氓皱，需要使用HTTP訪問极舔。但是在我們?nèi)粘Ｊ褂胹wagger接口文檔的時候撩扒，有的時候需要接口文檔離線訪問鸦列，如將文檔導(dǎo)出為html、markdown格式搪花。又或者我們不希望應(yīng)用系統(tǒng)與swagger接口文檔使用同一個服務(wù)遏片，而是導(dǎo)出HTML之后單獨部署，這樣做保證了對接口文檔的訪問不影響業(yè)務(wù)系統(tǒng)撮竿，也一定程度提高了接口文檔的安全性吮便。核心的實現(xiàn)過程就是：
在swagger2接口文檔所在的應(yīng)用內(nèi)，利用swagger2markup將接口文檔導(dǎo)出為adoc文件倚聚，也可以導(dǎo)出markdown文件线衫。
然后將adoc文件轉(zhuǎn)換為靜態(tài)的html格式，可以將html發(fā)布到nginx或者其他的web應(yīng)用容器惑折，提供訪問（本文不會講html靜態(tài)部署授账，只講HTML導(dǎo)出)。
注意：adoc是一種文件格式惨驶，不是我的筆誤白热。不是doc文件也不是docx文件。
一粗卜、maven依賴類庫
在已經(jīng)集成了swagger2的應(yīng)用內(nèi)屋确，通過maven坐標(biāo)引入相關(guān)依賴類庫,pom.xml代碼如下：
swagger2markup用于將swagger2在線接口文檔導(dǎo)出為html,markdown,adoc等格式文檔，用于靜態(tài)部署或離線閱讀续扔。其中第一個maven坐標(biāo)是必須的攻臀。后兩個maven坐標(biāo)，當(dāng)你在執(zhí)行后面的代碼過程中報下圖中的ERROR纱昧，或者有的類無法import的時候使用刨啸。
swagger2markup過程可能拋出的異常
產(chǎn)生異常的原因已經(jīng)有人在github的issues上給出解釋了：當(dāng)你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就會有異常發(fā)生。所以我們顯式的引入這兩個jar识脆，替換掉swagger2默認引入的這兩個jar设联。
swagger2markup異常的解決方案
二、生成adoc格式文件
下面的代碼是通過編碼方式實現(xiàn)的生成adoc格式文件的方式
使用RunWith注解和SpringBootTest注解灼捂，啟動應(yīng)用服務(wù)容器离例。 SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定義的端口，而不是隨機使用一個端口進行測試悉稠，這很重要宫蛆。
Swagger2MarkupConfig 是輸出文件的配置，如文件的格式和文件中的自然語言等
Swagger2MarkupConverter的from表示哪一個HTTP服務(wù)作為資源導(dǎo)出的源頭(JSON格式)的猛，可以自己訪問試一下這個鏈接洒扎。8888是我的服務(wù)端口辑甜，需要根據(jù)你自己的應(yīng)用配置修改。
toFile表示將導(dǎo)出文件存放的位置袍冷，不用加后綴名。也可以使用toFolder表示文件導(dǎo)出存放的路徑猫牡。二者區(qū)別在于使用toFolder導(dǎo)出為文件目錄下按標(biāo)簽TAGS分類的多個文件胡诗，使用toFile是導(dǎo)出一個文件（toFolder多個文件的合集）。
上面的這一段代碼是生成markdown格式接口文件的代碼淌友。執(zhí)行上面的2段單元測試代碼煌恢，就可以生產(chǎn)對應(yīng)格式的接口文件。
還有一種方式是通過maven插件的方式震庭，生成adoc和markdown格式的接口文件瑰抵。筆者不常使用這種方式，沒有使用代碼生成的方式配置靈活器联，很多配置都放到pom.xml感覺很臃腫二汛。但還是介紹一下,首先配置maven插件swagger2markup-maven-plugin。
然后運行插件swagger2markup就可以了拨拓，如下圖：
插件運行方式(點擊可放大)
三肴颊、通過maven插件生成HTML文檔
adoc的sourceDirectory路徑必須和第三小節(jié)中生成的adoc文件路徑一致。然后按照下圖方式運行插件渣磷。
asciidoctor:process-asciidoc插件運行
HTMl接口文檔顯示的效果如下婿着，有了HTML接口文檔你想轉(zhuǎn)成其他各種格式的文檔就太方便了，有很多工具可以使用醋界。這里就不一一介紹了竟宋。
推薦:SpringBoot系列精品文章（16章97節(jié)）, http://springboot.zimug.com
本號只做持續(xù)的知識輸出，希望您能關(guān)注形纺、評論丘侠、轉(zhuǎn)發(fā)！您的支持是我不竭的創(chuàng)作動力挡篓！讓知識產(chǎn)生價值婉陷、讓程序員改變世界！
