Swagger文檔轉Word 文檔

Swagger文檔轉Word 文檔

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

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

1、前言

    爲何會產生這個需求呢？

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

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

2、思路

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

一、解析JSON 文件

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

三、由html直接轉成word

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

      

3、實現

一、封裝對象

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

 Table

 Request

 Response

二、解析 json

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

    解析JSON真是一件枯燥的工做，你們能夠按照本身想要生成模板的樣子修改這邊的代碼......須要提的是，這裏有一點讓我糾結了很久。怎麼僞造接口的請求參數發送HTTP請求以免不會拋異常呢？最後仍是參考了Swagger的方式，即：若是是 String 類型的參數，就把這個參數置爲"string"；若是是 Integer 類型的參數，就把這個參數置爲 0 ；若是是Double 類型的參數，就置爲 0.0 ；若是是其餘沒辦法預見的類型，就所有置爲 null；

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

 TableServiceImpl

三、html 模板

咱們須要一個和 Word Table 模板同樣的HTML 頁面，而後利用JSP的 foreach 遍歷後臺獲得的 List<Table> 集合，一鼓作氣，生成全部接口......

 json.jsp

 四、效果

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

固然，剩下的工做，就要咱們手動去整理維護了。好比：把屬於同一個類的請求分類整理到一塊兒；把HTTP請求錯誤的返回值刪除（還沒法適配全部的HTTP請求狀況）；整理維護效果以下：

 

4、使用

    若是直接採用個人API文檔模板的話，只須要將 resources 目錄下的 data.json 文件的內容替換成本身的Swagger Json 文件內容就好。可是，考慮到咱們模板中的返回參數是咱們公司一個自定義的對象，因此可能這裏還須要你們根據本身的要求稍做修改，主要 修改TableServiceImpl 類下的 listResponse() 方法。

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

    另外，我以爲 TableServiceImpl  還有很大能夠改善的地方，代碼略顯冗餘。以後慢慢維護吧！固然，很歡迎你們一塊兒來開發...哈哈

5、結語

    一直以爲，IT最迷人的地方就是開源和分享，你們互不相識，即便沒有利益可圖，卻能爲同一個項目，相同的目標 貢獻本身的時間和精力。想一想就難以想象。寫這個博文的目地更可能是分享本身的創意和想法，說實話，代碼可能寫的有點爛。還請你們不要嫌棄，不吝指教！

6、更新說明

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

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

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

    如今的使用方式也更加簡單：

一、修改resources目錄下resources.properties文件的 swaggerUrl 爲Swagger Json資源的url地址。 二、服務啓動後：訪問 http://host(主機):port(端口)/getWord，etc：http://localhost:8080/getWord  三、將生成的getWord文件，增長後綴名 getWord.doc 。