目前，大家通常都是用Swagger來編寫Rest API文件，使用Swagger註解和Springfox，可以方便的從原始碼生成文件，保持文件和原始碼一致。使用Swagger-ui工具，介面的消費方可以檢視介面定義並從瀏覽器直接呼叫介面。如何實現Swagger和Spring Boot專案的結合，可以參考文章Spring Boot RESTful API Documentation With Swagger 2和Springfox的官方文件。

    但是，有時我們為其它讀者提供API文件，例如尊貴的客戶領導要驗收工作成果，Swagger UI就顯得不太正式了，而且要連線上執行Swagger UI的伺服器才可以完整的檢視。最近，筆者找到了工具swagger2markup和asciidoctor，結合起來使用就可以輸出優美的API文件了，供大家參考。

使用Swagger2Markup Demo

    筆者嘗試了多種方式後，發現結合swagger2markup和asciidoctor兩個工具需要較多的配置，Swagger2Markup Demo專案已經做好了基本的配置，是一個Quick-Wins的路徑。

樣例程式的使用

    從GitHub上克隆Swagger2Markup Demo專案，然後匯入WorkSpace。

    如上圖所示，在專案中，swagger2markup和asciidoctor是在pom.xml檔案中以Maven外掛的形式引入的，專案已經對兩個外掛做了配置。在src/docs/asciidoc目錄中，存放了生成最終文件的索引檔案，index.adoc的內容是：

include::{generated}/overview.adoc[]
include::manual_content1.adoc[]
include::manual_content2.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/security.adoc[]
include::{generated}/definitions.adoc[]

    {generated}目錄下的adoc檔案都是swagger2markup根據swagger生成的，同時，該檔案示例引入了兩個靜態檔案manual_content1.adoc和manual_content2.adoc。

    在專案上執行mvn clean test，執行成功後，即可在target/asciidoc/html目錄下找到生成的index.html文件，如下所示，是否覺得可讀性比Swagger UI好多了？

    還可以在target\asciidoc\pdf目錄中可以找到生成的index.pdf文件，不過當REST API文件中有中文時，生成的PDF會發生漏字的問題，無法使用。

    樣例程式的原理是springfox-staticdocs從API程式碼的註解生成了靜態的Swagger API文件swagger.json，並放在了target/swagger目錄下。swagger2markup讀取靜態的swagger.json檔案生成了asciidoctor所需的adoc檔案。下面一起來看看如何使用動態的Swagger API文件。

使用動態Swagger API文件

    假設專案的動態Swagger地址是http://localhost:6060/v2/api-docs，注意在瀏覽器中開啟應當看到一個JSON文件，而非Swagger UI。如圖，將spring-swagger2markup-demo專案pom.xml檔案中的swaggerInput標籤中的內容改為動態Swagger的地址。

    再次執行mvn clean test，即可在target/asciidoc/html目錄下找到新生成的index.html文件。

生成請求和響應的樣例JSON

    Swagger UI中有一個很棒的特性，就是可以顯示請求和響應的樣例JSON，便於介面的消費方使用。但在樣例中，生成的文件中並沒有樣例JSON，可以通過在swagger2markup Maven外掛中增加一項swagger2markup.generatedExamplesEnabled配置來增加樣例JSON，如圖：

   再次執行mvn clean test，即可在target/asciidoc/html目錄下找到新生成的index.html文件。可以看到生成的JSON樣例：

在文件中新增靜態章節

    前文中已經介紹了，樣例中演示瞭如何在index.adoc中引入靜態章節，我們可以利用這一特性新增一些Swagger沒有生成的內容，作為API文件的補充，如筆者在manual_content1.adoc中定義了一段碼錶內容：

== 碼錶

=== 性別

[options="header", cols=".^2,.^14"]
|===
|程式碼|含義
|**M**|男
|**F**|女
|===

     執行mvn clean test後，在文件中添加了以下的內容：

參考文獻

1. http://swagger2markup.github.io/swagger2markup/1.3.3/

2. https://asciidoctor.org/docs/asciidoc-syntax-quick-reference