Spring Boot 2.x基礎教程：Swagger靜態文檔的生成

  • 2019 年 10 月 16 日
  • 筆記

前言

通過之前的兩篇關於Swagger入門以及具體使用細節的介紹之後，我們已經能夠輕鬆地為Spring MVC的Web項目自動構建出API文檔了。如果您還不熟悉這塊，可以先閱讀：

在這兩篇文章中，我們構建的文檔必須通過在項目中整合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文檔一文中構建的項目。讀者可以通過下面的倉庫獲取：

接下來，我們將利用這個項目中的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

img

第二步：在彈出框的Insert選項中選擇Confluence Wiki，然後將生成的txt文件中的內容，黏貼在左側的輸入框中；此時，在右側的閱覽框可以看到如下圖的效果了。

img

注意：所以Insert選項中也提供了Markdown格式，我們也可以用上面生成的Markdown結果來使用，但是效果並不好，所以在Confluence中使用專門的生成結果為佳。

代碼示例

本文的完整工程可以查看下面倉庫中的chapter2-5目錄：

如果您覺得本文不錯，歡迎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

VirMach 便宜 VPS

QNews

QNews