前言
在學會了如何使用Swagger之后卡乾，我們已經(jīng)能夠輕松地為Spring MVC或SpringBoot的Web項目自動構建出API文檔了木柬。但是混移，構建的文檔必須通過在項目中整合swagger-ui救拉、或使用單獨部署的swagger-ui和/v2/api-docs返回的配置信息才能展現(xiàn)出您所構建的API文檔氏堤。本文將在使用Swagger的基礎上档插，再介紹一種生成靜態(tài)API文檔的方法慢蜓，以便于構建更輕量部署和使用的API文檔。
Swagger使用說明：REST API文檔工具Swagger2郭膛，以及與SpringBoot的集成
Swagger2Markup簡介
Swagger2Markup是Github上的一個開源項目晨抡。該項目主要用來將Swagger自動生成的文檔轉(zhuǎn)換成幾種流行的格式以便于靜態(tài)部署和使用，比如：AsciiDoc、Markdown耘柱、Confluence如捅。
項目主頁：https://github.com/Swagger2Markup/swagger2markup
如何使用
在使用Swagger2Markup之前，我們先需要準備一個使用了Swagger的Web項目帆谍，REST API文檔工具Swagger2伪朽，以及與SpringBoot的集成。
生成AsciiDoc
生成AsciiDoc的方式有兩種：
- 通過Java代碼來生成
第一步：編輯pom.xml增加需要使用的相關依賴和倉庫
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
</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>
第二步：編寫一個單元測試用例來生成執(zhí)行生成文檔的代碼
/**
* 生成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://127.0.0.1:8082/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:8082/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:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFolder(Paths.get("./docs/confluence/generated"));
}
/**
* 生成AsciiDocs格式文檔,并匯總成一個文件
* @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:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/asciidoc/generated/all"));
}
/**
* 生成Markdown格式文檔,并匯總成一個文件
* @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:8082/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/markdown/generated/all"));
}
以上代碼內(nèi)容很簡單汛蝙，大致說明幾個關鍵內(nèi)容：
-
MarkupLanguage.ASCIIDOC：指定了要輸出的最終格式烈涮。除了ASCIIDOC之外，還有MARKDOWN和CONFLUENCE_MARKUP -
from(new URL("http://localhost:8080/v2/api-docs")：指定了生成靜態(tài)部署文檔的源頭配置窖剑，可以是這樣的URL形式坚洽，也可以是符合Swagger規(guī)范的String類型或者從文件中讀取的流。如果是對當前使用的Swagger項目西土，我們通過使用訪問本地Swagger接口的方式讶舰，如果是從外部獲取的Swagger文檔配置文件，就可以通過字符串或讀文件的方式 -
toFolder(Paths.get("src/docs/asciidoc/generated")：指定最終生成文件的具體目錄位置
輸出到單個文件
如果不想分割結(jié)果文件需了，也可以通過替換toFolder(Paths.get("src/docs/asciidoc/generated")為toFile(Paths.get("src/docs/asciidoc/generated/all"))跳昼，將轉(zhuǎn)換結(jié)果輸出到一個單一的文件中，這樣可以最終生成html的也是單一的肋乍。
在執(zhí)行了上面的測試用例之后鹅颊，我們就能在當前項目的目錄下獲得如下內(nèi)容：
可以看到，這種方式在運行之后就生成出了5個不同的靜態(tài)文件墓造。
- 通過Maven插件來生成
除了通過上面編寫Java代碼來生成的方式之外堪伍，swagger2markup還提供了對應的Maven插件來使用。對于上面的生成方式觅闽，完全可以通過在pom.xml中增加如下插件來完成靜態(tài)內(nèi)容的生成帝雇。
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.6</version>
<configuration>
<sourceDirectory>./docs/asciidoc/generated</sourceDirectory>
<outputDirectory>./docs/asciidoc/html</outputDirectory>
<headerFooter>true</headerFooter>
<doctype>book</doctype>
<backend>html</backend>
<sourceHighlighter>coderay</sourceHighlighter>
<attributes>
<!--菜單欄在左邊-->
<toc>left</toc>
<!--多標題排列-->
<toclevels>3</toclevels>
<!--自動打數(shù)字序號-->
<sectnums>true</sectnums>
</attributes>
</configuration>
</plugin>
通過上面的配置，執(zhí)行該插件的asciidoctor:process-asciidoc命令之后蛉拙，就能在docs/asciidoc/html目錄下生成最終可用的靜態(tài)部署HTML了尸闸。在完成生成之后，可以直接通過瀏覽器來看查看刘离，你就能看到類似下圖的靜態(tài)部署結(jié)果：
騰訊云+社區(qū)邀請
我的博客即將搬運同步至騰訊云+社區(qū)室叉，邀請大家一同入駐：https://cloud.tencent.com/developer/support-plan?invite_code=1eyx9f4wbftcp
