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

在上一篇 《使用Swagger2Markup實作API文檔的靜态部署（一）：AsciiDoc》 中，我們介紹了如何使用

Swagger2Markup

将Swagger文檔轉換成AsciiDoc，再将AsciiDoc轉換成靜态HTML。下面，本文将繼續介紹Swagger2Markup可以轉換的另外兩種格式：Markdown和Confluence。

https://blog.didispace.com/swagger2markup-markdown-confluence/#Swagger2Markup%E7%AE%80%E4%BB%8B Swagger2Markup簡介

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

項目首頁：

https://github.com/Swagger2Markup/swagger2markup

https://blog.didispace.com/swagger2markup-markdown-confluence/#%E5%A6%82%E4%BD%95%E4%BD%BF%E7%94%A8 如何使用

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

https://blog.didispace.com/swagger2markup-markdown-confluence/#%E7%94%9F%E6%88%90Markdown%E5%92%8CConfluence 生成Markdown和Confluence

生成方式有一下兩種：

• 通過Java代碼來生成：隻需要修改

  withMarkupLanguage

  屬性來指定不同的格式以及

  toFolder

  屬性為結果指定不同的輸出目錄。

生成markdown的代碼片段：

wagger2MarkupConfig 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的也是單一的。

通過插件輸出方式類似，這裡不做贅述，如何引入插件可以檢視

上一篇文章

https://blog.didispace.com/swagger2markup-markdown-confluence/#%E9%9D%99%E6%80%81%E9%83%A8%E7%BD%B2 靜态部署

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

https://blog.didispace.com/swagger2markup-markdown-confluence/#Markdown%E7%9A%84%E9%83%A8%E7%BD%B2 Markdown的部署

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

https://blog.didispace.com/swagger2markup-markdown-confluence/#Confluence%E7%9A%84%E9%83%A8%E7%BD%B2 Confluence的部署

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

第一步：在Confluence的建立頁面的工具欄中選擇

{}Markup

第二步：在彈出框的

Insert

選項中選擇

Confluence Wiki

，然後将生成的txt檔案中的内容，黏貼在左側的輸入框中；此時，在右側的閱覽框可以看到如下圖的效果了。

注意：是以

Insert

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

https://blog.didispace.com/css/images/weixin-didispace.jpg