引言
在學(xué)會(huì)了使用 Swagger 之后，我們能夠輕松地為 SpringBoot 項(xiàng)目自動(dòng)構(gòu)建API文檔海渊。但是绵疲，我們構(gòu)建的文檔需要在項(xiàng)目中整合 swagger-ui 或使用單獨(dú)部署的 swagger-ui 和 /v2/api-docs 返回的配置信息才能展現(xiàn)出 API 文檔。這里我們將在使用 Swagger 的基礎(chǔ)上臣疑，介紹一種生成靜態(tài) API 文檔的方法盔憨，以便于構(gòu)建更輕量部署和使用的 API 文檔。
Swagger2Markup
Swagger2Markup 是 Github 上的開源項(xiàng)目讯沈。Swagger2Markup 可以將 Swagger 生成的文檔轉(zhuǎn)化成流行的格式以便于獨(dú)立部署和使用般渡，如：Markdown、Confluence芙盘、AsciiDoc驯用。
GitHub：https://github.com/Swagger2Markup/swagger2markup
生成AsciiDoc（Java代碼生成）
一、編輯 pom.xml 增加需要使用的相關(guān)依賴儒老、倉(cāng)庫(kù)和插件
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.1</version>
</dependency>
<!-- 引用以下兩個(gè)包是防止生成過程中出現(xiàn)找不到類的異常 -->
<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>
<!--測(cè)試依賴 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
<repositories>
<repository>
<snapshots>
<enabled>true</enabled>
<updatePolicy>always</updatePolicy>
</snapshots>
<id>jcenter-releases</id>
<name>jcenter</name>
<url>http://jcenter.bintray.com</url>
</repository>
</repositories>
<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<!-- asciidoc文件目錄 -->
<sourceDirectory>./docs</sourceDirectory>
<!-- 生成HTML的路徑 -->
<outputDirectory>./html</outputDirectory>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!-- 導(dǎo)航欄在左側(cè) -->
<toc>left</toc>
<!-- 顯示菜單層級(jí)數(shù) -->
<toclevels>3</toclevels>
<!-- 自動(dòng)打數(shù)字序號(hào) -->
<sectnums>ture</sectnums>
</attributes>
</configuration>
</plugin>
</plugins>
</build>
二蝴乔、編寫一個(gè)單元測(cè)試用例來生成執(zhí)行生成文檔的代碼
import java.net.URL;
import java.nio.file.Paths;
import org.junit.Test;
import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
public class Swagger2MarkupTest {
/**
* 生成AsciiDocs格式文檔
*
* @throws Exception
*/
@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:8080/v2/api-docs")).withConfig(config).build()
.toFolder(Paths.get("./docs/asciidoc/generated"));
}
/**
* 生成Markdown格式文檔
*
* @throws Exception
*/
@Test
public void generateMarkdownDocs() 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:8080/v2/api-docs")).withConfig(config).build()
.toFolder(Paths.get("./docs/markdown/generated"));
}
/**
* 生成Confluence格式文檔
*
* @throws Exception
*/
@Test
public void generateConfluenceDocs() throws Exception {
// 輸出Confluence使用的格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP).withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS).withGeneratedExamples().withoutInlineSchema().build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs")).withConfig(config).build()
.toFolder(Paths.get("./docs/confluence/generated"));
}
/**
* 生成AsciiDocs格式文檔,并匯總成一個(gè)文件
*
* @throws Exception
*/
@Test
public void generateAsciiDocsToFile() 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:8080/v2/api-docs")).withConfig(config).build()
.toFile(Paths.get("./docs/asciidoc/generated/all"));
}
/**
* 生成Markdown格式文檔,并匯總成一個(gè)文件
*
* @throws Exception
*/
@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:8080/v2/api-docs")).withConfig(config).build()
.toFile(Paths.get("./docs/markdown/generated/all"));
}
}
以上代碼說明了幾個(gè)關(guān)鍵內(nèi)容：
MarkupLanguage.ASCIIDOC：指定了要輸出的最終格式。除了ASCIIDOC之外驮樊，還有MARKDOWN和CONFLUENCE_MARKUP薇正。
from(new URL("http://localhost:8080/v2/api-docs")：指定了生成靜態(tài)文檔的數(shù)據(jù)源配置片酝。
toFolder(Paths.get("src/docs/asciidoc/generated")：指定了最終生成文件的目錄位置。如果不想分割結(jié)果文件挖腰，也可以改成toFile(Paths.get("src/docs/asciidoc/generated/all"))雕沿，將轉(zhuǎn)換結(jié)果輸出到一個(gè)文件中，這樣最終也只會(huì)生成一個(gè)html文件猴仑。
在執(zhí)行測(cè)試用例之后【執(zhí)行前需要運(yùn)行主服務(wù)审轮，也就是接口服務(wù)】，就能在當(dāng)前項(xiàng)目的目錄下獲得如下內(nèi)容：
生成離線文檔的代碼
三辽俗、通過cmd進(jìn)入到項(xiàng)目的pom.xml目錄下執(zhí)行以下命令
mvn asciidoctor:process-asciidoc
命令執(zhí)行完成即生成HTML文檔疾渣，文件結(jié)構(gòu)如下：
離線HTML文檔
四、文檔樣例如下：
