將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檔案。

一、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(""))
                .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(""))
            .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></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介面文件你想轉成其他各種格式的文件就太方便了，有很多工具可以使用。這裡就不一一介紹了。

期待您的關注

• 向您推薦博主的系列文件：
• 本文轉載註明出處（必須帶連線，不能只轉文字）：。