目前，大家通常都是用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
