Spring Boot 2.x基礎教程:Swagger靜態文件的生成
前言
通過之前的兩篇關於Swagger入門以及具體使用細節的介紹之後,我們已經能夠輕鬆地為Spring MVC的Web專案自動構建出API文件了。如果您還不熟悉這塊,可以先閱讀:
- Spring Boot 2.x基礎教程:使用Swagger2構建強大的API文件
- Spring Boot 2.x基礎教程:Swagger介面分類與各元素排序問題詳解
在這兩篇文章中,我們構建的文件必須通過在專案中整合swagger-ui
、或使用單獨部署的swagger-ui
和/v2/api-docs
返回的配置資訊才能展現出您所構建的API文件。而有些時候,我們可能只需要提供靜態文件給其他對接方的時候,我們要如何快速輕便的產生靜態API文件呢?
接下來我們就來學習一個解決該問題的工具:Swagger2Markup。
Swagger2Markup簡介
Swagger2Markup是Github上的一個開源專案。該專案主要用來將Swagger自動生成的文件轉換成幾種流行的格式以便於靜態部署和使用,比如:AsciiDoc、Markdown、Confluence。
專案主頁:https://github.com/Swagger2Markup/swagger2markup
如何使用
在使用Swagger2Markup之前,我們先需要準備一個使用了Swagger的Web專案,可以是直接使用Swagger2的專案,也可以使用Spring Boot 2.x基礎教程:使用Swagger2構建強大的API文件一文中構建的專案。讀者可以通過下面的倉庫獲取:
- Github:https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
- Gitee:https://gitee.com/didispace/SpringBoot-Learning/tree/2.x
接下來,我們將利用這個專案中的chapter2-2
模組作為基礎來來生成幾種不同格式的靜態文件。
生成 AsciiDoc 文件
生成 AsciiDoc 文件的方式有兩種:
通過Java程式碼來生成
第一步:編輯pom.xml
增加需要使用的相關依賴和倉庫
<dependencies> ... <dependency> <groupId>io.github.swagger2markup</groupId> <artifactId>swagger2markup</artifactId> <version>1.3.3</version> <scope>test</scope> </dependency> </dependencies> <repositories> <repository> <snapshots> <enabled>false</enabled> </snapshots> <id>jcenter-releases</id> <name>jcenter</name> <url>http://jcenter.bintray.com</url> </repository> </repositories>
本身這個工具主要就臨時用一下,所以這裡我們把scope
設定為test,這樣這個依賴就不會打包到正常執行環境中去。
第二步:編寫一個單元測試用例來生成執行生成文件的程式碼
@RunWith(SpringRunner.class)
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.DEFINED_PORT)
public class DemoApplicationTests {
@Test
public void generateAsciiDocs() throws Exception {
URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/asciidoc/generated");
// 輸出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)
.build();
Swagger2MarkupConverter.from(remoteSwaggerFile)
.withConfig(config)
.build()
.toFolder(outputDirectory);
}
}
以上程式碼內容很簡單,大致說明幾個關鍵內容:
MarkupLanguage.ASCIIDOC
:指定了要輸出的最終格式。除了ASCIIDOC
之外,還有MARKDOWN
和CONFLUENCE_MARKUP
,分別定義了其他格式,後面會具體舉例。from(remoteSwaggerFile
:指定了生成靜態部署文件的源頭配置,可以是這樣的URL形式,也可以是符合Swagger規範的String型別或者從檔案中讀取的流。如果是對當前使用的Swagger專案,我們通過使用訪問本地Swagger介面的方式,如果是從外部獲取的Swagger文件配置檔案,就可以通過字串或讀檔案的方式toFolder(outputDirectory)
:指定最終生成檔案的具體目錄位置
在執行了上面的測試用例之後,我們就能在當前專案的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.3</version>
<configuration>
<swaggerInput>http://localhost:8080/v2/api-docs</swaggerInput>
<outputDir>src/docs/asciidoc/generated-by-plugin</outputDir>
<config>
<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
</config>
</configuration>
</plugin>
在使用外掛生成前,需要先啟動應用。然後執行外掛,就可以在src/docs/asciidoc/generated-by-plugin
目錄下看到也生成了上面一樣的adoc檔案了。
生成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版之前的文件也是這樣的!!!
Markdown 與 Confluence 的支援
要生成Markdown和Confluence的方式非常簡單,與上一篇中的方法類似,只需要修改一個引數即可。
生成 Markdown 和 Confluence 文件
生成方式有一下兩種:
- 通過Java程式碼來生成:只需要修改
withMarkupLanguage
屬性來指定不同的格式以及toFolder
屬性為結果指定不同的輸出目錄。
生成markdown的程式碼片段:
URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/markdown/generated");
// 輸出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.build();
Swagger2MarkupConverter.from(remoteSwaggerFile)
.withConfig(config)
.build()
.toFolder(outputDirectory);
生成confluence的程式碼片段:
URL remoteSwaggerFile = new URL("http://localhost:8080/v2/api-docs");
Path outputDirectory = Paths.get("src/docs/confluence/generated");
// 輸出Ascii格式
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
.build();
Swagger2MarkupConverter.from(remoteSwaggerFile)
.withConfig(config)
.build()
.toFolder(outputDirectory);
在執行了上面的設定內容之後,我們就能在當前專案的src目錄下獲得如下內容:
src
--docs
----confluence
------generated
--------definitions.txt
--------overview.txt
--------paths.txt
--------security.txt
----markdown
------generated
--------definitions.md
--------overview.md
--------paths.md
--------security.md
可以看到,執行之後分別在markdown和confluence目錄下輸出了不同格式的轉換內容。如果讀者想要通過外掛來生成,直接參考上一節內容,只需要修改外掛配置中的swagger2markup.markupLanguage
即可支援輸出其他格式內容。
最後,我們一起來看看生成的Markdown和Confluence文件要怎麼使用
Markdown的部署
Markdown目前在文件編寫中使用非常常見,所以可用的靜態部署工具也非常多,比如:Hexo、Jekyll等都可以輕鬆地實現靜態化部署,也可以使用一些SaaS版本的文件工具,比如:語雀等。具體使用方法,這裡按照這些工具的文件都非常詳細,這裡就不具體介紹了。
Confluence的部署
相信很多團隊都使用Confluence作為文件管理系統,所以下面具體說說Confluence格式生成結果的使用。
第一步:在Confluence的新建頁面的工具欄中選擇{}Markup
第二步:在彈出框的Insert
選項中選擇Confluence Wiki
,然後將生成的txt檔案中的內容,黏貼在左側的輸入框中;此時,在右側的閱覽框可以看到如下圖的效果了。
注意:所以Insert
選項中也提供了Markdown格式,我們也可以用上面生成的Markdown結果來使用,但是效果並不好,所以在Confluence中使用專門的生成結果為佳。
程式碼示例
本文的完整工程可以檢視下面倉庫中的chapter2-5
目錄:
- Github:https://github.com/dyc87112/SpringBoot-Learning/tree/2.x
- Gitee:https://gitee.com/didispace/SpringBoot-Learning/tree/2.x
如果您覺得本文不錯,歡迎Star支援,您的關注是我堅持的動力!
參考資料
- [1] https://github.com/Swagger2Markup/swagger2markup
- [2] http://blog.didispace.com/swagger2markup-asciidoc/
- [3] http://blog.didispace.com/swagger2markup-markdown-confluence/
歡迎關注我的公眾號:程式猿DD,獲得獨家整理的學習資源和日常乾貨推送。
如果您對我的專題內容感興趣,也可以關注我的部落格:didispace.com