如何將Swagger2文檔導(dǎo)出為HTML或markdown等格式離線閱讀
這期內(nèi)容當(dāng)中小編將會(huì)給大家?guī)?lái)有關(guān)如何將Swagger2文檔導(dǎo)出為HTML或markdown等格式離線閱讀，文章內(nèi)容豐富且以專業(yè)的角度為大家分析和敘述，閱讀完這篇文章希望大家可以有所收獲。
創(chuàng)新互聯(lián)建站專注于企業(yè)成都營(yíng)銷網(wǎng)站建設(shè)、網(wǎng)站重做改版、岐山網(wǎng)站定制設(shè)計(jì)、自適應(yīng)品牌網(wǎng)站建設(shè)、H5頁(yè)面制作、商城網(wǎng)站制作、集團(tuán)公司官網(wǎng)建設(shè)、外貿(mào)營(yíng)銷網(wǎng)站建設(shè)、高端網(wǎng)站制作、響應(yīng)式網(wǎng)頁(yè)設(shè)計(jì)等建站業(yè)務(wù)，價(jià)格優(yōu)惠性價(jià)比高，為岐山等各大城市提供網(wǎng)站開發(fā)制作服務(wù)。
在我們?nèi)粘Ｊ褂胹wagger接口文檔的時(shí)候，有的時(shí)候需要接口文檔離線訪問(wèn)，如將文檔導(dǎo)出為html、markdown格式。又或者我們不希望應(yīng)用系統(tǒng)與swagger接口文檔使用同一個(gè)服務(wù)，而是導(dǎo)出HTML之后單獨(dú)部署，這樣做保證了對(duì)接口文檔的訪問(wèn)不影響業(yè)務(wù)系統(tǒng)，也一定程度提高了接口文檔的安全性。核心的實(shí)現(xiàn)過(guò)程就是：
在swagger2接口文檔所在的應(yīng)用內(nèi)，利用swagger2markup將接口文檔導(dǎo)出為adoc文件，也可以導(dǎo)出markdown文件。 然后將adoc文件轉(zhuǎn)換為靜態(tài)的html格式，可以將html發(fā)布到nginx或者其他的web應(yīng)用容器，提供訪問(wèn)（本文不會(huì)講html靜態(tài)部署，只講HTML導(dǎo)出)。
注意：adoc是一種文件格式，不是我的筆誤。不是doc文件也不是docx文件。
一、maven依賴類庫(kù)
在已經(jīng)集成了swagger2的應(yīng)用內(nèi)，通過(guò)maven坐標(biāo)引入相關(guān)依賴類庫(kù),pom.xml代碼如下：
swagger2markup用于將swagger2在線接口文檔導(dǎo)出為html,markdown,adoc等格式文檔，用于靜態(tài)部署或離線閱讀。其中第一個(gè)maven坐標(biāo)是必須的。后兩個(gè)maven坐標(biāo)，當(dāng)你在執(zhí)行后面的代碼過(guò)程中報(bào)下圖中的ERROR，或者有的類無(wú)法import的時(shí)候使用。
產(chǎn)生異常的原因已經(jīng)有人在github的issues上給出解釋了：當(dāng)你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就會(huì)有異常發(fā)生。所以我們顯式的引入這兩個(gè)jar，替換掉swagger2默認(rèn)引入的這兩個(gè)jar。
二、生成adoc格式文件
下面的代碼是通過(guò)編碼方式實(shí)現(xiàn)的生成adoc格式文件的方式
@RunWith(SpringRunner.class)@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)public class DemoApplicationTests { @Test public void generateAsciiDocs() throws Exception { // 輸出Ascii格式 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.ASCIIDOC) //設(shè)置生成格式 .withOutputLanguage(Language.ZH) //設(shè)置語(yǔ)言中文還是其他語(yǔ)言 .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("src/main/resources/docs/asciidoc")); }}
使用RunWith注解和SpringBootTest注解，啟動(dòng)應(yīng)用服務(wù)容器。 SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定義的端口，而不是隨機(jī)使用一個(gè)端口進(jìn)行測(cè)試，這很重要。
Swagger2MarkupConfig 是輸出文件的配置，如文件的格式和文件中的自然語(yǔ)言等
Swagger2MarkupConverter的from表示哪一個(gè)HTTP服務(wù)作為資源導(dǎo)出的源頭(JSON格式)，可以自己訪問(wèn)試一下這個(gè)鏈接。8888是我的服務(wù)端口，需要根據(jù)你自己的應(yīng)用配置修改。
toFile表示將導(dǎo)出文件存放的位置，不用加后綴名。也可以使用toFolder表示文件導(dǎo)出存放的路徑。二者區(qū)別在于使用toFolder導(dǎo)出為文件目錄下按標(biāo)簽TAGS分類的多個(gè)文件，使用toFile是導(dǎo)出一個(gè)文件（toFolder多個(gè)文件的合集）。
@Testpublic void generateMarkdownDocsToFile() throws Exception { // 輸出Markdown到單文件 Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder() .withMarkupLanguage(MarkupLanguage.MARKDOWN) .withOutputLanguage(Language.ZH) .withPathsGroupedBy(GroupBy.TAGS) .withGeneratedExamples() .withoutInlineSchema() .build(); Swagger2MarkupConverter.from(new URL("http://localhost:8888/v2/api-docs")) .withConfig(config) .build() .toFile(Paths.get("src/main/resources/docs/markdown"));}
上面的這一段代碼是生成markdown格式接口文件的代碼。執(zhí)行上面的2段單元測(cè)試代碼，就可以生產(chǎn)對(duì)應(yīng)格式的接口文件。
還有一種方式是通過(guò)maven插件的方式，生成adoc和markdown格式的接口文件。筆者不常使用這種方式，沒(méi)有使用代碼生成的方式配置靈活，很多配置都放到pom.xml感覺(jué)很臃腫。但還是介紹一下,首先配置maven插件swagger2markup-maven-plugin。
然后運(yùn)行插件就可以了，如下圖：
三、通過(guò)maven插件生成HTML文檔
adoc的sourceDirectory路徑必須和第三小節(jié)中生成的adoc文件路徑一致。然后按照下圖方式運(yùn)行插件。
HTMl接口文檔顯示的效果如下，有了HTML接口文檔你想轉(zhuǎn)成其他各種格式的文檔就太方便了，有很多工具可以使用。這里就不一一介紹了。
上述就是小編為大家分享的如何將Swagger2文檔導(dǎo)出為HTML或markdown等格式離線閱讀了，如果剛好有類似的疑惑，不妨參照上述分析進(jìn)行理解。如果想知道更多相關(guān)知識(shí)，歡迎關(guān)注創(chuàng)新互聯(lián)行業(yè)資訊頻道。
本文標(biāo)題：如何將Swagger2文檔導(dǎo)出為HTML或markdown等格式離線閱讀
文章網(wǎng)址：http://m.jiaotiyi.com/article/gcosde.html