將Swagger2文檔導出爲HTML或markdown等格式離線閱讀

網上有不少《使用swagger2構建API文檔》的文章，該文檔是一個在線文檔，須要使用HTTP訪問。可是在咱們平常使用swagger接口文檔的時候，有的時候須要接口文檔離線訪問，如將文檔導出爲html、markdown格式。又或者咱們不但願應用系統與swagger接口文檔使用同一個服務，而是導出HTML以後單獨部署，這樣作保證了對接口文檔的訪問不影響業務系統，也必定程度提升了接口文檔的安全性。核心的實現過程就是：

• 在swagger2接口文檔所在的應用內，利用swagger2markup將接口文檔導出爲adoc文件，也能夠導出markdown文件。
• 而後將adoc文件轉換爲靜態的html格式，能夠將html發佈到nginx或者其餘的web應用容器，提供訪問（本文不會講html靜態部署，只講HTML導出)。

> 注意：adoc是一種文件格式，不是個人筆誤。不是doc文件也不是docx文件。

1、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。

2、生成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>

而後運行插件就能夠了，以下圖：

3、經過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接口文檔你想轉成其餘各類格式的文檔就太方便了，有不少工具能夠使用。這裏就不一一介紹了。

期待您的關注

• 向您推薦博主的系列文檔：《手摸手教您學習SpringBoot系列-16章97節》
• 本文轉載註明出處（必須帶鏈接，不能只轉文字）：字母哥博客。