懶得寫文檔,swagger文檔導(dǎo)出來不香嗎
點擊上方藍(lán)色字體，選擇“標(biāo)星公眾號”
優(yōu)質(zhì)文章，第一時間送達
? 作者?|??唯一浩哥
來源 |? urlify.cn/YJ3AFn
前言
??早前筆者曾經(jīng)寫過一篇文章《研發(fā)團隊,請管好你的API文檔》。團隊協(xié)作中,開發(fā)文檔的重要性,這里就不再贅述,今天的話題集中在如何進一步提升更加高效的使用文檔。
離線文檔
??swagger已經(jīng)很方便了,我們?yōu)槭裁催€需要離線文檔?公司同一個項目組,一般只要集成了swagger基本就夠了,但是難免會有跨組,甚至?xí)泄緦ν夂献鞯捻椖俊Ｌ貏e是在"微服務(wù)大行其道的今天",多個團隊之間,因為分工不同,權(quán)限不同,往往不能互相訪問各個項目的swagger文檔,通常的做法有以下幾種:
搭建統(tǒng)一的接口文檔管理系統(tǒng)
每個項目組的都要將各自的接口手動編寫到歸檔到這里,需要查看,把人拉入組織即可查看。
代碼即文檔
提供源代碼。同一個項目開發(fā)開發(fā)者。很多小公司就是這樣。沒有文檔,只有源碼。
離線文檔
將文檔導(dǎo)出成excel,docx,html等形式,對外輸出,比如給第三方調(diào)用。
??本文將聚焦于如何將swaggerUI導(dǎo)出離線文檔。
??筆者嘗試了以下三種方式。
1 保存為html
Web開發(fā)者都知道,只要是網(wǎng)頁你都可以另存為靜態(tài)網(wǎng)頁。
然后,右鍵用谷歌瀏覽器打開
當(dāng)我運行我的代碼時，它出錯了：
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有關(guān)系,還好對swagger有所了解。果斷通過訪問 http://localhost:5000/swagger/v1/swagger.json 下載swagger.json,并放在指定位置。
??再次運行,報錯和剛才一樣。這是跨源資源共享問題。
有兩種處理辦法:
使用網(wǎng)絡(luò)服務(wù)器。
要為靜態(tài)html/js文件運行一個簡單的Web服務(wù)器。
更改您的chrome啟動參數(shù)，并讓它知道您要忽略此安全功能。
詳細(xì)請查閱:https://www.codenong.com/50445639/
這里我使用的是IIS服務(wù)器,將js和html一同部署在IIS上,如下:
更改您的chrome啟動參數(shù)，并讓它知道您要忽略此安全功能。
??部署之后,通過部署的IP地址即可訪問(PS:這個比較適合公司內(nèi)部,比如前后端分離開發(fā)的是時候)。
2 導(dǎo)出成pdf文檔?
這個比較簡單,不用寫代碼。利用windows自帶的功能即可實現(xiàn)。
點擊快捷鍵Ctrl+p，顯示打印頁面
保存即可。
3 導(dǎo)出成Word文檔
??當(dāng)然,盡管以上兩種方式已經(jīng)很方便了。可是總有些時候，遇到一些難纏的，又不講道理，偏偏覺得將Swagger文檔地址丟給客戶會不夠正式！死活要一份word文檔。
??可是這個時候，如果接口數(shù)量上百個，甚至更多，一個一個手動輸入word，那將是一筆耗時的工作。但卻有什么辦法可以解決呢？
??對了，利用Swagge生成的Json文件轉(zhuǎn)換為word文檔不就可以了嗎？
實現(xiàn)方式
獲取Swagger接口文檔的Json文件
解析Json文件數(shù)據(jù)填充到Html的表格中
根據(jù)生成的html轉(zhuǎn)work文檔
??這就需要在swagger文檔代碼中做一些擴展。詳情可以參考:基于.NetCore3.1系列 —— 使用Swagger導(dǎo)出文檔
??導(dǎo)出word的格式如下:
基于swagger生成的文檔數(shù)據(jù),我們就可以按照自己的想法來生成自定義格式的數(shù)據(jù)了。有興趣的童鞋可以繼續(xù)深挖。
參考
基于.NetCore3.1系列 —— 使用Swagger導(dǎo)出文檔
https://www.codenong.com/50445639/
https://www.52interview.com/book/18/200
研發(fā)團隊,請管好你的API文檔
粉絲福利：實戰(zhàn)springboot+CAS單點登錄系統(tǒng)視頻教程免費領(lǐng)取
???
?長按上方微信二維碼?2 秒 即可獲取資料
感謝點贊支持下哈?