Spring Boot 2.x基礎教程：Swagger靜態文檔的生成

時間 2019-11-05

標籤 spring boot 2.x 基礎教程 swagger 靜態文檔生成欄目 Spring 简体版

原文原文鏈接

前言

經過以前的兩篇關於Swagger入門以及具體使用細節的介紹以後，咱們已經可以輕鬆地爲Spring MVC的Web項目自動構建出API文檔了。若是您還不熟悉這塊，能夠先閱讀：html

在這兩篇文章中，咱們構建的文檔必須經過在項目中整合swagger-ui、或使用單獨部署的swagger-ui和/v2/api-docs返回的配置信息才能展示出您所構建的API文檔。而有些時候，咱們可能只須要提供靜態文檔給其餘對接方的時候，咱們要如何快速輕便的產生靜態API文檔呢？java

接下來咱們就來學習一個解決該問題的工具：Swagger2Markup。git

Swagger2Markup簡介

Swagger2Markup是Github上的一個開源項目。該項目主要用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用，好比：AsciiDoc、Markdown、Confluence。github

項目主頁：https://github.com/Swagger2Markup/swagger2markupweb

如何使用

在使用Swagger2Markup以前，咱們先須要準備一個使用了Swagger的Web項目，能夠是直接使用Swagger2的項目，也可使用Spring Boot 2.x基礎教程：使用Swagger2構建強大的API文檔一文中構建的項目。讀者能夠經過下面的倉庫獲取：spring

接下來，咱們將利用這個項目中的chapter2-2模塊做爲基礎來來生成幾種不一樣格式的靜態文檔。api

生成 AsciiDoc 文檔

生成 AsciiDoc 文檔的方式有兩種：瀏覽器

經過Java代碼來生成

第一步：編輯pom.xml增長鬚要使用的相關依賴和倉庫markdown

<dependencies>
    ...

    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.3</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

自己這個工具主要就臨時用一下，因此這裏咱們把scope設置爲test，這樣這個依賴就不會打包到正常運行環境中去。maven

第二步：編寫一個單元測試用例來生成執行生成文檔的代碼

@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {

    @Test
    public void generateAsciiDocs() throws Exception {

        URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
        Path outputDirectory = Paths.get("src/docs/asciidoc/generated");

        //    輸出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();


        Swagger2MarkupConverter.from(remoteSwaggerFile)
                .withConfig(config)
                .build()
                .toFolder(outputDirectory);
    }

}

以上代碼內容很簡單，大體說明幾個關鍵內容：

MarkupLanguage.ASCIIDOC：指定了要輸出的最終格式。除了ASCIIDOC以外，還有MARKDOWN和CONFLUENCE_MARKUP，分別定義了其餘格式，後面會具體舉例。
from(remoteSwaggerFile：指定了生成靜態部署文檔的源頭配置，能夠是這樣的URL形式，也能夠是符合Swagger規範的String類型或者從文件中讀取的流。若是是對當前使用的Swagger項目，咱們經過使用訪問本地Swagger接口的方式，若是是從外部獲取的Swagger文檔配置文件，就能夠經過字符串或讀文件的方式
toFolder(outputDirectory)：指定最終生成文件的具體目錄位置

在執行了上面的測試用例以後，咱們就能在當前項目的src目錄下得到以下內容：

src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc

能夠看到，這種方式在運行以後就生成出了4個不一樣的靜態文件。

輸出到單個文件

若是不想分割結果文件，也能夠經過替換toFolder(Paths.get("src/docs/asciidoc/generated")爲toFile(Paths.get("src/docs/asciidoc/generated/all"))，將轉換結果輸出到一個單一的文件中，這樣能夠最終生成html的也是單一的。

經過 Maven 插件來生成

除了經過上面編寫Java代碼來生成的方式以外，swagger2markup還提供了對應的Maven插件來使用。對於上面的生成方式，徹底能夠經過在pom.xml中增長以下插件來完成靜態內容的生成。

<plugin>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup-maven-plugin</artifactId>
    <version>1.3.3</version>
    <configuration>
        <swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
        <outputDir>src/docs/asciidoc/generated-by-plugin</outputDir>
        <config>
            <swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
        </config>
    </configuration>
</plugin>

在使用插件生成前，須要先啓動應用。而後執行插件，就能夠在src/docs/asciidoc/generated-by-plugin目錄下看到也生成了上面同樣的adoc文件了。

生成HTML

在完成了從Swagger文檔配置文件到AsciiDoc的源文件轉換以後，就是如何將AsciiDoc轉換成可部署的HTML內容了。這裏繼續在上面的工程基礎上，引入一個Maven插件來完成。

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <toc>left</toc>
        </attributes>
    </configuration>
</plugin>

經過上面的配置，執行該插件的asciidoctor:process-asciidoc命令以後，就能在src/docs/asciidoc/html目錄下生成最終可用的靜態部署HTML了。在完成生成以後，能夠直接經過瀏覽器來看查看，你就能看到相似下圖的靜態部署結果：

是否是感受似曾相識呢？是的，Spring Cloud的E版以前的文檔也是這樣的！！！

Markdown 與 Confluence 的支持

要生成Markdown和Confluence的方式很是簡單，與上一篇中的方法相似，只須要修改一個參數便可。

生成 Markdown 和 Confluence 文檔

生成方式有一下兩種：

經過Java代碼來生成：只須要修改withMarkupLanguage屬性來指定不一樣的格式以及toFolder屬性爲結果指定不一樣的輸出目錄。

生成markdown的代碼片斷：

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/markdown/generated");

//    輸出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build();

Swagger2MarkupConverter.from(remoteSwaggerFile)
    .withConfig(config)
    .build()
    .toFolder(outputDirectory);

生成confluence的代碼片斷：

URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/confluence/generated");

//    輸出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
    .build();

Swagger2MarkupConverter.from(remoteSwaggerFile)
    .withConfig(config)
    .build()
    .toFolder(outputDirectory);

在執行了上面的設置內容以後，咱們就能在當前項目的src目錄下得到以下內容：

src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md

能夠看到，運行以後分別在markdown和confluence目錄下輸出了不一樣格式的轉換內容。若是讀者想要經過插件來生成，直接參考上一節內容，只須要修改插件配置中的swagger2markup.markupLanguage便可支持輸出其餘格式內容。

最後，咱們一塊兒來看看生成的Markdown和Confluence文檔要怎麼使用