網上有很多《使用swagger2構建API文檔》的文章，該文檔是一個在線文檔，需要使用HTTP訪問。但是在我們日常使用swagger接口文檔的時候，有的時候需要接口文檔離線訪問，如將文檔導出為html、markdown格式。又或者我們不希望應用系統與swagger接口文檔使用同一個服務，而是導出HTML之後單獨部署，這樣做保證了對接口文檔的訪問不影響業務系統，也一定程度提高了接口文檔的安全性。核心的實現過程就是：
- 在swagger2接口文檔所在的應用內，利用swagger2markup將接口文檔導出為adoc文件，也可以導出markdown文件。
- 然後將adoc文件轉換為靜態的html格式，可以將html發布到nginx或者其他的web應用容器，提供訪問（本文不會講html靜態部署，只講HTML導出)。
注意：adoc是一種文件格式，不是我的筆誤。不是doc文件也不是docx文件。
一、maven依賴類庫
在已經集成了swagger2的應用內，通過maven坐標引入相關依賴類庫,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在線接口文檔導出為html,markdown,adoc等格式文檔，用於靜態部署或離線閱讀。其中第一個maven坐標是必須的。后兩個maven坐標，當你在執行後面的代碼過程中報下圖中的ERROR，或者有的類無法import的時候使用。
產生異常的原因已經有人在github的issues上給出解釋了：當你使用swagger-core版本大於等於1.5.11,並且swagger-models版本小於1.5.11就會有異常發生。所以我們顯式的引入這兩個jar，替換掉swagger2默認引入的這兩個jar。
二、生成adoc格式文件
下面的代碼是通過編碼方式實現的生成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) //設置生成格式
.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/asciidoc"));
}
}- 使用RunWith註解和SpringBootTest註解，啟動應用服務容器。 SpringBootTest.WebEnvironment.DEFINED_PORT表示使用application.yml定義的端口，而不是隨機使用一個端口進行測試，這很重要。
- Swagger2MarkupConfig 是輸出文件的配置，如文件的格式和文件中的自然語言等
- Swagger2MarkupConverter的from表示哪一個HTTP服務作為資源導出的源頭(JSON格式)，可以自己訪問試一下這個鏈接。8888是我的服務端口，需要根據你自己的應用配置修改。
- toFile表示將導出文件存放的位置，不用加後綴名。也可以使用toFolder表示文件導出存放的路徑。二者區別在於使用toFolder導出為文件目錄下按標籤TAGS分類的多個文件，使用toFile是導出一個文件（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格式接口文件的代碼。執行上面的2段單元測試代碼，就可以生產對應格式的接口文件。
還有一種方式是通過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>
<!--導航欄在左-->
<toc>left</toc>
<!--显示層級數-->
<!--<toclevels>3</toclevels>-->
<!--自動打数字序號-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>adoc的sourceDirectory路徑必須和第三小節中生成的adoc文件路徑一致。然後按照下圖方式運行插件。
HTMl接口文檔显示的效果如下，有了HTML接口文檔你想轉成其他各種格式的文檔就太方便了，有很多工具可以使用。這裏就不一一介紹了。
期待您的關注
- 向您推薦博主的系列文檔：
- 本文轉載註明出處（必須帶連接，不能只轉文字）：。
本站聲明:網站內容來源於博客園,如有侵權,請聯繫我們,我們將及時處理【其他文章推薦】
※台北網頁設計公司這麼多，該如何挑選?? 網頁設計報價省錢懶人包"嚨底家"
※網頁設計公司推薦更多不同的設計風格，搶佔消費者視覺第一線
※想知道購買電動車哪裡補助最多?台中電動車補助資訊懶人包彙整
