在閱讀本文之前，您先需要了解Swagger的使用，如果您還不知道它是用來干嘛的质帅，請(qǐng)先閱讀《Spring Boot中使用Swagger2構(gòu)建強(qiáng)大的RESTful API文檔》一文。
前言
在學(xué)會(huì)了如何使用Swagger之后，我們已經(jīng)能夠輕松地為Spring MVC的Web項(xiàng)目自動(dòng)構(gòu)建出API文檔了账磺。但是，如前文方式構(gòu)建的文檔必須通過在項(xiàng)目中整合swagger-ui痊远、或使用單獨(dú)部署的swagger-ui和/v2/api-docs返回的配置信息才能展現(xiàn)出您所構(gòu)建的API文檔垮抗。本文將在使用Swagger的基礎(chǔ)上，再介紹一種生成靜態(tài)API文檔的方法碧聪，以便于構(gòu)建更輕量部署和使用的API文檔冒版。
Swagger2Markup簡(jiǎn)介
Swagger2Markup是Github上的一個(gè)開源項(xiàng)目。該項(xiàng)目主要用來將Swagger自動(dòng)生成的文檔轉(zhuǎn)換成幾種流行的格式以便于靜態(tài)部署和使用逞姿，比如：AsciiDoc辞嗡、Markdown、Confluence滞造。
項(xiàng)目主頁：https://github.com/Swagger2Markup/swagger2markup
如何使用
在使用Swagger2Markup之前续室，我們先需要準(zhǔn)備一個(gè)使用了Swagger的Web項(xiàng)目，可以是直接使用Swagger2的項(xiàng)目谒养，也可以是使用了spring-boot-starter-swagger的項(xiàng)目挺狰，比如我倉庫中的：https://github.com/dyc87112/swagger-starter-demo ，下面就來看看如何使用Swagger2Markup來創(chuàng)建AsciiDoc。
生成AsciiDoc
生成AsciiDoc的方式有兩種：
- 通過Java代碼來生成
第一步：編輯pom.xml增加需要使用的相關(guān)依賴和倉庫
<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>
第二步：編寫一個(gè)單元測(cè)試用例來生成執(zhí)行生成文檔的代碼
@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"));
}
}
以上代碼內(nèi)容很簡(jiǎn)單丰泊，大致說明幾個(gè)關(guān)鍵內(nèi)容：
-
MarkupLanguage.ASCIIDOC：指定了要輸出的最終格式薯定。除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUP -
from(new URL("http://localhost:8080/v2/api-docs")：指定了生成靜態(tài)部署文檔的源頭配置瞳购，可以是這樣的URL形式话侄，也可以是符合Swagger規(guī)范的String類型或者從文件中讀取的流。如果是對(duì)當(dāng)前使用的Swagger項(xiàng)目学赛，我們通過使用訪問本地Swagger接口的方式年堆，如果是從外部獲取的Swagger文檔配置文件，就可以通過字符串或讀文件的方式 -
toFolder(Paths.get("src/docs/asciidoc/generated")：指定最終生成文件的具體目錄位置
在執(zhí)行了上面的測(cè)試用例之后罢屈，我們就能在當(dāng)前項(xiàng)目的src目錄下獲得如下內(nèi)容：
src
--docs
----asciidoc
------generated
--------definitions.adoc
--------overview.adoc
--------paths.adoc
--------security.adoc
可以看到嘀韧，這種方式在運(yùn)行之后就生成出了4個(gè)不同的靜態(tài)文件。
輸出到單個(gè)文件
如果不想分割結(jié)果文件缠捌，也可以通過替換toFolder(Paths.get("src/docs/asciidoc/generated")為toFile(Paths.get("src/docs/asciidoc/generated/all"))锄贷，將轉(zhuǎn)換結(jié)果輸出到一個(gè)單一的文件中，這樣可以最終生成html的也是單一的曼月。
- 通過Maven插件來生成
除了通過上面編寫Java代碼來生成的方式之外谊却，swagger2markup還提供了對(duì)應(yīng)的Maven插件來使用。對(duì)于上面的生成方式哑芹，完全可以通過在pom.xml中增加如下插件來完成靜態(tài)內(nèi)容的生成炎辨。
<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的源文件轉(zhuǎn)換之后聪姿，就是如何將AsciiDoc轉(zhuǎn)換成可部署的HTML內(nèi)容了碴萧。這里繼續(xù)在上面的工程基礎(chǔ)上，引入一個(gè)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>
通過上面的配置破喻，執(zhí)行該插件的asciidoctor:process-asciidoc命令之后，就能在src/docs/asciidoc/html目錄下生成最終可用的靜態(tài)部署HTML了盟榴。在完成生成之后曹质，可以直接通過瀏覽器來看查看，你就能看到類似下圖的靜態(tài)部署結(jié)果：
是不是感覺似曾相識(shí)呢擎场？是的羽德，Spring Cloud的E版之前的文檔也是這樣的！Ｑ赴臁宅静！
