導航
- 前言
- 離線文件
- 1 儲存為html
- 2 匯出成pdf文件
- 3 匯出成Word文件
- 參考
前言
早前筆者曾經寫過一篇文章《研發團隊,請管好你的API文件》。團隊協作中,開發文件的重要性,這裡就不再贅述,今天的話題集中在如何進一步提升更加高效的使用文件。
離線文件
swagger已經很方便了,我們為什麼還需要離線文件?公司同一個專案組,一般只要整合了swagger基本就夠了,但是難免會有跨組,甚至會有公司對外合作的專案。特別是在"微服務大行其道的今天",多個團隊之間,因為分工不同,許可權不同,往往不能互相訪問各個專案的swagger文件,通常的做法有以下幾種:
-
搭建統一的介面文件管理系統
每個專案組的都要將各自的介面手動編寫到歸檔到這裡,需要檢視,把人拉入組織即可檢視。
-
程式碼即文件
提供原始碼。同一個專案開發開發者。很多小公司就是這樣。沒有文件,只有原始碼。
-
離線文件
將文件匯出成excel,docx,html等形式,對外輸出,比如給第三方呼叫。
本文將聚焦於如何將swaggerUI匯出離線文件。
筆者嘗試了以下三種方式。
1 儲存為html
Web開發者都知道,只要是網頁你都可以另存為靜態網頁。
然後,右鍵用谷歌瀏覽器開啟
當我執行我的程式碼時，它出錯了：
swagger-ui-bundle.js:6 Fetch API cannot load file:///C:/swagger/v1/swagger.json. URL scheme must be "http" or "https" for CORS request.
很明顯和swagger.json有關係,還好對swagger有所瞭解。果斷通過訪問 http://localhost:5000/swagger/v1/swagger.json 下載swagger.json,並放在指定位置。
再次執行,報錯和剛才一樣。這是跨源資源共享問題。
有兩種處理辦法:
-
使用網路伺服器。
要為靜態html/js檔案執行一個簡單的Web伺服器。
-
更改您的chrome啟動引數，並讓它知道您要忽略此安全功能。
這裡我使用的是IIS伺服器,將js和html一同部署在IIS上,如下:
- 更改您的chrome啟動引數，並讓它知道您要忽略此安全功能。
部署之後,通過部署的IP地址即可訪問(PS:這個比較適合公司內部,比如前後端分離開發的是時候)。
2 匯出成pdf文件
這個比較簡單,不用寫程式碼。利用windows自帶的功能即可實現。
點選快捷鍵Ctrl+p，顯示列印頁面
儲存即可。
3 匯出成Word文件
當然,儘管以上兩種方式已經很方便了。可是總有些時候，遇到一些難纏的，又不講道理，偏偏覺得將Swagger文件地址丟給客戶會不夠正式！死活要一份word文件。
可是這個時候，如果介面數量上百個，甚至更多，一個一個手動輸入word，那將是一筆耗時的工作。但卻有什麼辦法可以解決呢？
對了，利用Swagge生成的Json檔案轉換為word文件不就可以了嗎？
實現方式
-
獲取Swagger介面文件的Json檔案
-
解析Json檔案資料填充到Html的表格中
-
根據生成的html轉work文件
這就需要在swagger文件程式碼中做一些擴充套件。詳情可以參考:基於.NetCore3.1系列 —— 使用Swagger匯出文件
匯出word的格式如下:
基於swagger生成的文件資料,我們就可以按照自己的想法來生成自定義格式的資料了。有興趣的童鞋可以繼續深挖。