在閱讀本文之前,您先需要了解Swagger的使用,如果您還不知道它是用來幹嘛的,請先閱讀《Spring Boot中使用Swagger2構建強大的RESTful API文檔》一文。
前言
在學會了如何使用Swagger之後,我們已經能夠輕鬆地爲Spring MVC的Web項目自動構建出API文檔了。但是,如前文方式構建的文檔必須通過在項目中整合swagger-ui
、或使用單獨部署的swagger-ui
和/v2/api-docs
返回的配置信息才能展現出您所構建的API文檔。本文將在使用Swagger的基礎上,再介紹一種生成靜態API文檔的方法,以便於構建更輕量部署和使用的API文檔。
Swagger2Markup簡介
Swagger2Markup是Github上的一個開源項目。該項目主要用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用,比如:AsciiDoc、Markdown、Confluence。
項目主頁:https://github.com/Swagger2Markup/swagger2markup
如何使用
在使用Swagger2Markup之前,我們先需要準備一個使用了Swagger的Web項目,可以是直接使用Swagger2的項目,也可以是使用了spring-boot-starter-swagger的項目,比如我倉庫中的:https://github.com/dyc87112/swagger-starter-demo ,下面就來看看如何使用Swagger2Markup來創建AsciiDoc。
生成AsciiDoc
生成AsciiDoc的方式有兩種:
- 通過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_MARKUPfrom(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的也是單一的。
- 通過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版之前的文檔也是這樣的!!!