導航
- 前言
- 離線文檔
- 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生成的文檔數據,我們就可以按照自己的想法來生成自定義格式的數據了。有興趣的童鞋可以繼續深挖。