溫馨提示×
您好，登錄后才能下訂單哦！
點擊 登錄注冊 即表示同意《億速云用戶服務(wù)條款》
您好，登錄后才能下訂單哦！
網(wǎng)上有很多《使用swagger2構(gòu)建API文檔》的文章，該文檔是一個在線文檔，需要使用HTTP訪問。但是在我們?nèi)粘Ｊ褂胹wagger接口文檔的時候，有的時候需要接口文檔離線訪問，如將文檔導(dǎo)出為html、markdown格式。又或者我們不希望應(yīng)用系統(tǒng)與swagger接口文檔使用同一個服務(wù)，而是導(dǎo)出HTML之后單獨部署，這樣做保證了對接口文檔的訪問不影響業(yè)務(wù)系統(tǒng)，也一定程度提高了接口文檔的安全性。核心的實現(xiàn)過程就是：
注意：adoc是一種文件格式，不是我的筆誤。不是doc文件也不是docx文件。
一、maven依賴類庫
在已經(jīng)集成了swagger2的應(yīng)用內(nèi)，通過maven坐標(biāo)引入相關(guān)依賴類庫,pom.xml代碼如下：
<dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.1</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-core</artifactId> <version>1.5.16</version> </dependency> <dependency> <groupId>io.swagger</groupId> <artifactId>swagger-models</artifactId> <version>1.5.16</version> </dependency>
swagger2markup用于將swagger2在線接口文檔導(dǎo)出為html,markdown,adoc等格式文檔，用于靜態(tài)部署或離線閱讀。其中第一個maven坐標(biāo)是必須的。后兩個maven坐標(biāo)，當(dāng)你在執(zhí)行后面的代碼過程中報下圖中的ERROR，或者有的類無法import的時候使用。
產(chǎn)生異常的原因已經(jīng)有人在github的issues上給出解釋了：當(dāng)你使用swagger-core版本大于等于1.5.11,并且swagger-models版本小于1.5.11就會有異常發(fā)生。所以我們顯式的引入這兩個jar，替換掉swagger2默認(rèn)引入的這兩個jar。
二、生成adoc格式文件
下面的代碼是通過編碼方式實現(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è)置語言中文還是其他語言
.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注解，啟動應(yīng)用服務(wù)容器。 SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定義的端口，而不是隨機(jī)使用一個端口進(jìn)行測試，這很重要。
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多個文件的合集）。
@Test
public 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段單元測試代碼，就可以生產(chǎn)對應(yīng)格式的接口文件。
還有一種方式是通過maven插件的方式，生成adoc和markdown格式的接口文件。筆者不常使用這種方式，沒有使用代碼生成的方式配置靈活，很多配置都放到pom.xml感覺很臃腫。但還是介紹一下,首先配置maven插件swagger2markup-maven-plugin。
<plugin> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup-maven-plugin</artifactId> <version>1.3.1</version> <configuration> <swaggerInput>http://localhost:8888/v2/api-docs</swaggerInput><!---swagger-api-json路徑--> <outputDir>src/main/resources/docs/asciidoc</outputDir><!---生成路徑--> <config> <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage><!--生成格式--> </config> </configuration> </plugin>
然后運行插件就可以了，如下圖：
三、通過maven插件生成HTML文檔
<plugin> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctor-maven-plugin</artifactId> <version>1.5.6</version> <configuration> <!--asciidoc文件目錄--> <sourceDirectory>src/main/resources/docs</sourceDirectory> <!---生成html的路徑--> <outputDirectory>src/main/resources/html</outputDirectory> <backend>html</backend> <sourceHighlighter>coderay</sourceHighlighter> <attributes> <!--導(dǎo)航欄在左--> <toc>left</toc> <!--顯示層級數(shù)--> <!--<toclevels>3</toclevels>--> <!--自動打數(shù)字序號--> <sectnums>true</sectnums> </attributes> </configuration> </plugin>
adoc的sourceDirectory路徑必須和第三小節(jié)中生成的adoc文件路徑一致。然后按照下圖方式運行插件。
HTMl接口文檔顯示的效果如下，有了HTML接口文檔你想轉(zhuǎn)成其他各種格式的文檔就太方便了，有很多工具可以使用。這里就不一一介紹了。
總結(jié)
以上所述是小編給大家介紹的將Swagger2文檔導(dǎo)出為HTML或markdown等格式離線閱讀解析，希望對大家有所幫助，如果大家有任何疑問請給我留言，小編會及時回復(fù)大家的。在此也非常感謝大家對億速云網(wǎng)站的支持！
如果你覺得本文對你有幫助，歡迎轉(zhuǎn)載，煩請注明出處，謝謝！
免責(zé)聲明：本站發(fā)布的內(nèi)容（圖片、視頻和文字）以原創(chuàng)、轉(zhuǎn)載和分享為主，文章觀點不代表本網(wǎng)站立場，如果涉及侵權(quán)請聯(lián)系站長郵箱：is@yisu.com進(jìn)行舉報，并提供相關(guān)證據(jù)，一經(jīng)查實，將立刻刪除涉嫌侵權(quán)內(nèi)容。
億速云公眾號
手機(jī)網(wǎng)站二維碼