GitHub 地址：https://github.com/JMCuixy/SwaggerToWord/tree/developer

原創作品，轉載請註明出處：http://www.cnblogs.com/jmcui/p/8298823.html

一、前言

為什麽會產生這個需求呢？

我們公司作為乙方，老是被客戶追著要一份API文檔，當我們把一個 Swagger 文檔地址丟給客戶的時候。客戶還是很不滿意，嫌不夠正式！！死活堅持要一份 word 文檔 。然後領導給了個接口模板，就把這個活交給我了......我去，近10個微服務，幾百個接口，這不得要了我的命啊（最後整理出來將近200頁的 word 文檔）。最後，還是領導有辦法：要不我們把Swagger的 json文件轉成word文檔吧！

一直堅持一句話。作為使用者，人要遷就機器；作為開發者，要機器遷就人。

二、思路

領導提供了一個接口模板，類似下面這樣，其實就是一個word的table頁。想到 html 可以轉 word ，那麽問題就變成了 ：

1、解析JSON 文件

2、把JSON文件的內容填充進html 的Table中

3、由html直接轉成word

幾百個接口，一氣呵成！如下，還有一個簡單的示例，就是請求參數 和 返回值 。怎麽處理呢？在程序中寫了 HTTP 的請求，封裝了需要的參數去執行了一個請求，得到相應的返回值！

三、實現

1、封裝對象

按照面向對象的思想，一個接口Table就是一個對象，可變的請求參數和返回參數也封裝成一個對象......

2、解析 json

先來看看Swagger json文件的格式吧！需要註意的是這個 json 文件默認的 host 是沒有加 http:// 前綴的，需要我們手動加上，因為程序的HTTP請求不像瀏覽器一樣會自動補上 http:// 的前綴 ......

解析JSON真是一件枯燥的工作，大家可以按照自己想要生成模板的樣子修改這邊的代碼......需要提的是，這裏有一點讓我糾結了好久。怎麽偽造接口的請求參數發送HTTP請求以避免不會拋異常呢？最後還是參考了Swagger的方式，即：如果是 String 類型的參數，就把這個參數置為"string"；如果是 Integer 類型的參數，就把這個參數置為 0 ；如果是Double 類型的參數，就置為 0.0 ；如果是其他沒辦法預見的類型，就全部置為 null；

解析 JSON 用的是Spring推薦的 jackson ，這部分感覺沒什麽好說的，直接上代碼吧！

3、html 模板

我們需要一個和 Word Table 模板一樣的HTML 頁面，然後利用JSP的 foreach 遍歷後臺得到的 List<Table> 集合，一氣呵成，生成所有接口......

4、效果

把代碼運行起來後，訪問JSP頁面，不會像平常一樣看到 HTML 頁面，而是直接下載生成一個 文件，按照SpringMVC請求方法命名（這個項目中是getJson文件）。把這個文件的後綴名改成 .doc 就能看到效果了！差不多是如下效果：

當然，剩下的工作，就要我們手動去整理維護了。比如：把屬於同一個類的請求分類整理到一起；把HTTP請求錯誤的返回值刪除（還無法適配所有的HTTP請求情況）；整理維護效果如下：

四、使用

如果直接采用我的API文檔模板的話，只需要將 resources 目錄下的 data.json 文件的內容替換成自己的Swagger Json 文件內容就好。但是，考慮到我們模板中的返回參數是我們公司一個自定義的對象，所以可能這裏還需要大家根據自己的要求稍作修改，主要 修改TableServiceImpl 類下的 listResponse() 方法。

需要說明的是，這個項目還沒有很好的支持所有的HTTP請求，比如 restful 服務將請求參數放在請求路徑中的；比如參數是放在header中的；以及一系列可能沒有考慮到的bug......

另外，我覺得 TableServiceImpl 還有很大可以改善的地方，代碼略顯冗余。之後慢慢維護吧！當然，很歡迎大家一起來開發...哈哈

五、結語

一直覺得，IT最迷人的地方就是開源和分享，大家互不相識，即使沒有利益可圖，卻能為同一個項目，相同的目標 貢獻自己的時間和精力。想想就不可思議。寫這個博文的目地更多是分享自己的創意和想法，說實話，代碼可能寫的有點爛。還請大家不要嫌棄，不吝指教！

Swagger文檔轉Word