在閱讀本文之前,您先需要了解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/13001260824/swagger
如何使用
在使用Swagger2Markup之前,我們先需要準備一個使用了Swagger的Web項目,可以是直接使用Swagger2的項目,也可以是使用了spring-boot-starter-swagger的項目,比如我倉庫中的:https://github.com/13001260824/swagger ,下面就來看看如何使用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> |
第二步:編寫一個單元測試用例來生成執行生成文檔的代碼
(SpringRunner.class) (webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)public class DemoApplicationTests { 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的也是單一的。
- 通過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了。在完成生成之後,可以直接通過瀏覽器來看查看,你就能看到類似下圖的靜態部署結果: