參考早前筆者曾經寫過一篇文章《研發團隊,請管好你的api文件》。團隊協作中,開發文件的重要性,這裡就不再贅述,今天的話題集中在如何進一步提公升更加高效的使用文件。
離線文件
swagger已經很方便了,我們為什麼還需要離線文件?公司同乙個專案組,一般只要整合了swagger基本就夠了,但是難免會有跨組,甚至會有公司對外合作的專案。特別是在"微服務大行其道的今天",多個團隊之間,因為分工不同,許可權不同,往往不能互相訪問各個專案的swagger文件,通常的做法有以下幾種:
本文將聚焦於如何將swaggerui匯出離線文件。
筆者嘗試了以下三種方式。
1 儲存為html
web開發者都知道,只要是網頁你都可以另存為靜態網頁。
然後,右鍵用谷歌瀏覽器開啟
當我執行我的**時，它出錯了：
再次執行,報錯和剛才一樣。這是跨源資源共享問題。
有兩種處理辦法:
詳細請查閱:這裡我使用的是iis伺服器,將js和html一同部署在iis上,如下:
部署之後,通過部署的ip位址即可訪問(ps:這個比較適合公司內部,比如前後端分離開發的是時候)。
2 匯出成pdf文件
這個比較簡單,不用寫**。利用windows自帶的功能即可實現。
點選快捷鍵ctrl+p，顯示列印頁面
儲存即可。
3 匯出成word文件
當然,儘管以上兩種方式已經很方便了。可是總有些時候，遇到一些難纏的，又不講道理，偏偏覺得將swagger文件位址丟給客戶會不夠正式！死活要乙份word文件。
可是這個時候，如果介面數量上百個，甚至更多，乙個乙個手動輸入word，那將是一筆耗時的工作。但卻有什麼辦法可以解決呢？
對了，利用swagge生成的json檔案轉換為word文件不就可以了嗎？
實現方式
這就需要在swagger文件**中做一些擴充套件。詳情可以參考:基於.netcore3.1系列 —— 使用swagger匯出文件
匯出word的格式如下:
基於swagger生成的文件資料,我們就可以按照自己的想法來生成自定義格式的資料了。有興趣的童鞋可以繼續深挖。
Swagger介面文件
api 用在類上，說明該類的作用。apioperation 註解來給api增加方法說明。apiimplicitparams 用在方法上包含一組引數說明。apiimplicitparam 用來註解來給方法入參增加說明。apiresponses 用於表示一組響應 apiresponse 用在 apire...
Swagger文件使用
有很多人不清楚swagger ui的路徑，由於我們使用了更為好用的swagger bootstrap ui，實際上使 網域名稱 埠 doc.html，如 http localhost 8080 doc.html 在沒有swagger之前，我們需要自己手寫文件，手寫文件的出現問題 文件更新時需要要與前...
寫文件呀寫文件
最近在糾結產品文件的撰寫，文件寫的詳細點吧，有點羅嗦，寫的簡單些呢，就感覺內容不夠，怕使用者神馬其他人看不懂.所以決定，先寫多點，再在其中選擇一些不必要的話去刪減！好方法 額，還發現，學好小學語文很重要的了！關於書面語和口語的問題，必須必須得好好斟酌的呀！文件給不同的人看，貌似有不同的書寫方法呢！如...