一.未使用Swagger狀況 相信無論是前端開發人員還是後端開發人員,都或多或少都被介面文檔折磨過,前端經常抱怨後端給的介面文檔或與實際情況不一致。後端又覺得編寫及維護介面文檔會耗費不少精力,經常來不及更新。 其實無論是前端調用後端,還是後端調用後端,都期望有一個好的介面文檔。但是這個介面文檔對於程 ...
一.未使用Swagger狀況
相信無論是前端開發人員還是後端開發人員,都或多或少都被介面文檔折磨過,前端經常抱怨後端給的介面文檔或與實際情況不一致。後端又覺得編寫及維護介面文檔會耗費不少精力,經常來不及更新。 其實無論是前端調用後端,還是後端調用後端,都期望有一個好的介面文檔。但是這個介面文檔對於程式員來說,就跟註釋一樣,經常會抱怨別人寫的代碼沒有寫註釋,然而自己寫起代碼起來,最討厭的,也是寫註釋。 所以僅僅只通過強制來規範大家是不夠的,隨著時間推移,版本迭代,介面文檔往往很容易就跟不上代碼了
二.使用Swagger狀況
Swagger 提供了一個可視化的UI頁面展示描述文件,其中包括介面的調用,介面所需參數(header,body,url.params),介面說明,參數說明等。介面的調用方、測試、項目經理等都可以在該頁面中對相關介面進行查閱和做一些簡單的介面請求。只要在項目框架搭建時,對Swagger 進行了配置,後面持續迭代的時候,只會花很小代價去維護代碼、介面文檔以及Swagger描述文件。因為一旦介面發生改變,程式重新部署,介面文檔會重新生成對應新的文檔。
三.如何使用?
在NetCore項目中怎麼去使用Swagger來生成介面文檔呢?
首先在 webApi 啟動項目 上 右鍵 點擊管理Nuget程式包, 安裝 Swashbuckle.AspNetCore ,然後到 Startup 中添加引用 using Swashbuckle.AspNetCore.Swagger;
在ConfigureServices方法中添加以下代碼
#region Swagger services.AddSwaggerGen(options => { options.SwaggerDoc("v1", new Info { Version = "v1", Title = "API Doc", Description = "作者:Levy_w_Wang", //服務條款 TermsOfService = "None", //作者信息 Contact = new Contact { Name = "levy", Email = "[email protected]", Url = "https://www.cnblogs.com/levywang" }, //許可證 License = new License { Name = "tim", Url = "https://www.cnblogs.com/levywang" } }); #region XmlComments var basePath1 = Path.GetDirectoryName(typeof(Program).Assembly.Location);//獲取應用程式所在目錄(絕對,不受工作目錄(平臺)影響,建議採用此方法獲取路徑) //獲取目錄下的XML文件 顯示註釋等信息 var xmlComments = Directory.GetFiles(basePath1, "*.xml", SearchOption.AllDirectories).ToList(); foreach (var xmlComment in xmlComments) { options.IncludeXmlComments(xmlComment); } #endregion options.DocInclusionPredicate((docName, description) => true); options.IgnoreObsoleteProperties();//忽略 有Obsolete 屬性的方法 options.IgnoreObsoleteActions(); options.DescribeAllEnumsAsStrings(); }); #endregion
上面寫的迴圈是因為項目中可能有多個控制器類庫,為的是排除這種情況
接下來,再到 Configure 方法中添加:
#region Swagger app.UseSwagger(c => { c.RouteTemplate = "apidoc/{documentName}/swagger.json"; }); app.UseSwaggerUI(c => { c.RoutePrefix = "apidoc"; c.SwaggerEndpoint("v1/swagger.json", "ContentCenter API V1"); c.DocExpansion(DocExpansion.Full);//預設文檔展開方式 }); #endregion
這裡使用了 RoutePrefix 屬性,為的是改變原始打開介面文檔目錄,原始路徑為 swagger/index.html ,現在為 /apidoc/index.html
這個時候在需要輸出註釋的控制器類庫的屬性 中設置如下信息,並添加上相關註釋
然後運行起來,打開本地地址加上 /apidoc/index.html 就可以看到效果,
特別提醒:如果打開下麵這個界面能正常顯示,但是提示 Fetch errorInternal Server Error v1/swagger.json 錯誤,說明有方法未指明請求方式,如 HttpGet HttpPost HttpPut 等,找到並指明,重新運行就正常了
點擊方法右上角的 Try it out ,試下調用介面,然後點擊Exectue,執行查看結果,能得到後端方法返回結果就說明成功。
特別說明:有介面不需要展示出去的時候,可以在方法上添加屬性 Obsolete ,這樣就不會顯示出來。 前提:有前面ConfigureServices中 後面的 忽略 有Obsolete 屬性的方法 設置才行!!!
最後可以看到介面返回數據正常,並且也能看到介面響應請求嘛等等信息,一個介面應該返回的信息也都有顯示。
總結:
本文從為開發人員手寫api文檔的痛楚,從而引申出Swagger根據代碼自動生成出文檔和註釋,
並且還可以將不需要的方法不顯示等設置。然後進行了簡單的測試使用 。
但是!!一般後端方法都有token等驗證,需要在header中添加token、sid等欄位來驗證用戶,保障安全性,
該設置將在下一章節中寫!
以上若有什麼不對或可以改進的地方,望各位指出或提出意見,一起探討學習~
有需要源碼的可通過此 GitHub 鏈接拉取 覺得還可以的給個 start 和點個 下方的推薦哦~~謝謝!