Swagger文件轉Word 文件

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

原創作品，轉載請註明出處：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請求方法命名（這個專案中是getWord檔案）。把這個檔案的字尾名改成 .doc 就能看到效果了！差不多是如下效果：

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

四、使用

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

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

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

五、結語

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

六、更新說明

    之前看《Spring In Action》的時候，發現了 RestTemplate 這個東西， 作為取代 HttpClients 的請求方式。當時就在想，要是放在這個專案中不是恰到好處？

    2018-06-21 整理髮布了 1.2 版本，更新說明如下：

1、引入了Spring的RestTemplate取代 HttpClients 以支援更多的Restful請求。
2、命名規範以及增加異常處理，對於無法處理的HTTP請求返回空字串。
3、修改之前匯入data.josn的方式，變成restTemplate.getForObject("SwaggerJson的url地址",Map.class);的動態獲取方式。

    現在的使用方式也更加簡單：

1、修改resources目錄下resources.properties檔案的 swaggerUrl 為Swagger Json資源的url地址。
2、服務啟動後：訪問 http://host(主機):port(埠)/getWord，etc：http://localhost:8080/getWord 
3、將生成的getWord檔案，增加字尾名 getWord.doc 。