Swagger文檔轉Word 文檔
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就是一個對象，可變的請求參數和返回參數也封裝成一個對象......
Table
Request
Response
2、解析 json
先來看看Swagger json文件的格式吧！需要注意的是這個 json 文件默認的 host 是沒有加 http:// 前綴的，需要我們手動加上，因為程序的HTTP請求不像瀏覽器一樣會自動補上 http:// 的前綴 ......
解析JSON真是一件枯燥的工作，大家可以按照自己想要生成模板的樣子修改這邊的代碼......需要提的是，這里有一點讓我糾結了好久。怎么偽造接口的請求參數發送HTTP請求以避免不會拋異常呢？最后還是參考了Swagger的方式，即：如果是 String 類型的參數，就把這個參數置為"string"；如果是 Integer 類型的參數，就把這個參數置為 0 ；如果是Double 類型的參數，就置為 0.0 ；如果是其他沒辦法預見的類型，就全部置為 null；
解析 JSON 用的是Spring推薦的 jackson ，這部分感覺沒什么好說的，直接上代碼吧！
TableServiceImpl
3、html 模板
我們需要一個和 Word Table 模板一樣的HTML 頁面，然后利用JSP的 foreach 遍歷后台得到的 List<Table> 集合，一氣呵成，生成所有接口......
json.jsp
4、效果
把代碼運行起來后，訪問JSP頁面，不會像平常一樣看到 HTML 頁面，而是直接下載生成一個 文件，按照SpringMVC請求方法命名（這個項目中是getJson文件）。把這個文件的后綴名改成 .doc 就能看到效果了！差不多是如下效果：
當然，剩下的工作，就要我們手動去整理維護了。比如：把屬於同一個類的請求分類整理到一起；把HTTP請求錯誤的返回值刪除（還無法適配所有的HTTP請求情況）；整理維護效果如下：
四、使用
如果直接采用我的API文檔模板的話，只需要將 resources 目錄下的 data.json 文件的內容替換成自己的Swagger Json 文件內容就好。但是，考慮到我們模板中的返回參數是我們公司一個自定義的對象，所以可能這里還需要大家根據自己的要求稍作修改，主要 修改TableServiceImpl 類下的 listResponse() 方法。
需要說明的是，這個項目還沒有很好的支持所有的HTTP請求，比如 restful 服務將請求參數放在請求路徑中的；比如參數是放在header中的；以及一系列可能沒有考慮到的bug......
另外，我覺得 TableServiceImpl 還有很大可以改善的地方，代碼略顯冗余。之后慢慢維護吧！當然，很歡迎大家一起來開發...哈哈
五、結語
一直覺得，IT最迷人的地方就是開源和分享，大家互不相識，即使沒有利益可圖，卻能為同一個項目，相同的目標 貢獻自己的時間和精力。想想就不可思議。寫這個博文的目地更多是分享自己的創意和想法，說實話，代碼可能寫的有點爛。還請大家不要嫌棄，不吝指教！