使用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 = newSwagger2MarkupConfigBuilder().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 = newSwagger2MarkupConfigBuilder().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選項中選擇
ConfluenceWiki，然後將生成的txt檔案中的內容，黏貼在左側的輸入框中；此時，在右側的閱覽框可以看到如下圖的效果了。
注意：所以
Insert選項中也提供了Markdown格式，我們也可以用上面生成的Markdown結果來使用，但是效果並不好，所以在Confluence中使用專門的生成結果為佳。