使用Swagger2Markup實作API文檔的靜态部署（一）：AsciiDoc

在閱讀本文之前，您先需要了解Swagger的使用，如果您還不知道它是用來幹嘛的，請先閱讀 《Spring Boot中使用Swagger2建構強大的RESTful API文檔》 一文。

https://blog.didispace.com/swagger2markup-asciidoc/#%E5%89%8D%E8%A8%80 前言

在學會了如何使用Swagger之後，我們已經能夠輕松地為Spring MVC的Web項目自動建構出API文檔了。但是，如前文方式建構的文檔必須通過在項目中整合

swagger-ui

、或使用單獨部署的

swagger-ui

和

/v2/api-docs

傳回的配置資訊才能展現出您所建構的API文檔。本文将在使用Swagger的基礎上，再介紹一種生成靜态API文檔的方法，以便于建構更輕量部署和使用的API文檔。

https://blog.didispace.com/swagger2markup-asciidoc/#Swagger2Markup%E7%AE%80%E4%BB%8B Swagger2Markup簡介

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

項目首頁：

https://github.com/Swagger2Markup/swagger2markup

https://blog.didispace.com/swagger2markup-asciidoc/#%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8 如何使用

在使用Swagger2Markup之前，我們先需要準備一個使用了Swagger的Web項目，可以是直接使用Swagger2的項目，也可以是使用了

spring-boot-starter-swagger

的項目，比如我倉庫中的：

https://github.com/dyc87112/swagger-starter-demo

，下面就來看看如何使用Swagger2Markup來建立AsciiDoc。

https://blog.didispace.com/swagger2markup-asciidoc/#%E7%94%9F%E6%88%90AsciiDoc 生成AsciiDoc

生成AsciiDoc的方式有兩種：

1. 通過Java代碼來生成

第一步：編輯

pom.xml

增加需要使用的相關依賴和倉庫

<dependencies>
    ...

    <dependency>
        <groupId>io.github.swagger2markup</groupId>
        <artifactId>swagger2markup</artifactId>
        <version>1.3.1</version>
    </dependency>
</dependencies>

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

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

@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)
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFolder(Paths.get("src/docs/asciidoc/generated"));
    }

}      

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

• MarkupLanguage.ASCIIDOC

  ：指定了要輸出的最終格式。除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUP

• from(new URL("http://localhost:8080/v2/api-docs")

  ：指定了生成靜态部署文檔的源頭配置，可以是這樣的URL形式，也可以是符合Swagger規範的String類型或者從檔案中讀取的流。如果是對目前使用的Swagger項目，我們通過使用通路本地Swagger接口的方式，如果是從外部擷取的Swagger文檔配置檔案，就可以通過字元串或讀檔案的方式

• toFolder(Paths.get("src/docs/asciidoc/generated")

  ：指定最終生成檔案的具體目錄位置

在執行了上面的測試用例之後，我們就能在目前項目的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的也是單一的。

1. 通過Maven插件來生成

除了通過上面編寫Java代碼來生成的方式之外，swagger2markup還提供了對應的Maven插件來使用。對于上面的生成方式，完全可以通過在

pom.xml

中增加如下插件來完成靜态内容的生成。

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

生成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版之前的文檔也是這樣的！！！