使用Swagger2Markup實現API文檔的靜態部署（二）：Markdown和Confluence

在上一篇《使用Swagger2Markup實現API文檔的靜態部署（一）：AsciiDoc》中，我們介紹瞭如何使用Swagger2Markup將Swagger文檔轉換成AsciiDoc，再將AsciiDoc轉換成靜態HTML。下面，本文將繼續介紹Swagger2Markup可以轉換的另外兩種格式：Markdown和Confluence。

Swagger2Markup簡介

Swagger2Markup是Github上的一個開源項目。該項目主要用來將Swagger自動生成的文檔轉換成幾種流行的格式以便於靜態部署和使用，比如：AsciiDoc、Markdown、Confluence。

項目主頁：https://github.com/Swagger2Markup/swagger2markup

如何使用

要生成Markdown和Confluence的方式非常簡單，與上一篇中的方法類似，只需要修改一個參數即可。

生成Markdown和Confluence

生成方式有一下兩種：

• 通過Java代碼來生成：只需要修改withMarkupLanguage屬性來指定不同的格式以及toFolder屬性爲結果指定不同的輸出目錄。

生成markdown的代碼片段：

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.MARKDOWN)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/markdown/generated"));

生成confluence的代碼片段：

Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
    .withMarkupLanguage(MarkupLanguage.CONFLUENCE_MARKUP)
    .build();

Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
    .withConfig(config)
    .build()
    .toFolder(Paths.get("src/docs/confluence/generated"));

在執行了上面的設置內容之後，我們就能在當前項目的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目錄下輸出了不同格式的轉換內容。

輸出到單個文件

如果不想分割結果文件，也可以通過替換toFolder(Paths.get("src/docs/asciidoc/generated")爲toFile(Paths.get("src/docs/asciidoc/generated/all"))，將轉換結果輸出到一個單一的文件中，這樣可以最終生成html的也是單一的。

通過插件輸出方式類似，這裏不做贅述，如何引入插件可以查看上一篇文章

靜態部署

下面來看看Markdown和Confluence生成結果的使用。

Markdown的部署

Markdown目前在文檔編寫中使用非常常見，所以可用的靜態部署工具也非常多，比如：Hexo、Jekyll等都可以輕鬆地實現靜態化部署。具體使用方法，這裏按照這些工具的文檔都非常詳細，這裏就不具體介紹了。

Confluence的部署

相信很多團隊都使用Confluence作爲文檔管理系統，所以下面具體說說Confluence格式生成結果的使用。

第一步：在Confluence的新建頁面的工具欄中選擇{}Markup

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

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

本文首發：http://blog.didispace.com/swagger2markup-markdown-confluence/