1. <dd id="erndk"></dd>
                1. .netcore 3.1高性能微服務架構:加入swagger接口文檔

                  管理員 2020/2/22 16:04:50

                  swagger是什么?Swagger 是一個規范和完整的框架,用于生成、描述、調用和可視化 RESTful 風格的 Web 服務??傮w目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法,參數和模型緊密集成到服務器端的代碼,允許API來始終保持同步。swagger作用 (1)接口…


                  swagger是什么?


                  Swagger 是一個規范和完整的框架,用于生成、描述、調用和可視化 RESTful 風格的 Web 服務??傮w目標是使客戶端和文件系統作為服務器以同樣的速度來更新。文件的方法,參數和模型緊密集成到服務器端的代碼,允許API來始終保持同步。
                  111-0.png

                  swagger作用 


                    (1)接口的文檔在線自動生成。 
                    (2)功能測試。


                  接口開發的痛點

                  相信無論是前端還是后端開發,都或多或少地被接口文檔折磨過。前端經常抱怨后端給的接口文檔與實際情況不一致。后端又覺得編寫及維護接口文檔會耗費不少精力,經常來不及更新。其實無論是前端調用后端,還是后端調用后端,都期望有一個好的接口文檔。但是這個接口文檔對于程序員來說,就跟注釋一樣,經常會抱怨別人寫的代碼沒有寫注釋,然而自己寫起代碼起來,最討厭的,也是寫注釋。所以僅僅只通過強制來規范大家是不夠的,隨著時間推移,版本迭代,接口文檔往往很容易就跟不上代碼了。
                   
                  但即便如此,對于許多開發來說,編寫這個yml或json格式的描述文件,本身也是有一定負擔的工作,特別是在后面持續迭代開發的時候,往往會忽略更新這個描述文件,直接更改代碼。久而久之,這個描述文件也和實際項目漸行漸遠,基于該描述文件生成的接口文檔也失去了參考意義。所以再Java屆服務端的大一統框架Spring,迅速將Swagger規范納入自身的標準,建立了Spring-swagger項目,后面改成了現在的Springfox。通過在項目中引入Springfox,可以掃描相關的代碼,生成該描述文件,進而生成與代碼一致的接口文檔和客戶端代碼。而.Net生態,自從webapi2.0開始便開始使用Swagger作為接口文檔,到.NetCore生化后,Swagger更是普通使用的接口文檔規范,最常使用的組件就是Swashbuckle.AspNetCore。
                  這種通過代碼生成接口文檔的形式,在后面需求持續迭代的項目中,顯得尤為重要和高效。


                  .NetCore3.1中如何使用Swagger呢?


                  第一步:引入Swagger

                  用Vs2019創建.NetCore3.1的WebApi項目后,在VS2019里依次點擊  “工具”-“NuGet包管理器(N)”-"管理解決方案的NuGet程序包(N)",打開后,搜索“Swashbuckle.AspNetCore”,選擇最新版(目前最新版本為5.0.0),解決方案的項目列表里勾選WebApi項目,其他的項目(比如Domain,Common,Infrastructure)不需要勾選。點擊“安裝即可”。
                  111-001.png


                  111-2.png

                  第二步:Startup配置

                  1、ConfigureServices方法里將Swagger加入到容器IServiceCollection里,,并且指定讀取站點目錄下所有的xml文件,代碼如下:

                   services.AddSwaggerGen(c =>
                  {
                   c.SwaggerDoc("v1", new OpenApiInfo { Version = "v1", Title = "zyiz.net系統WebApi" });
                                   
                                  var dir = new DirectoryInfo(AppContext.BaseDirectory);
                                  foreach (FileInfo file in dir.EnumerateFiles("*.xml"))
                                  {
                                      c.IncludeXmlComments(file.FullName);
                                  }
                              });

                  2、Configure方法里開啟SwaggerUI,代碼如下:

                   app.UseSwagger().UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "MuXue.Zyiz.net API V1"); });


                  第三步:設置并且生成xml文件


                  1、解決方案-WebApi項目名右擊---“屬性”,點“生成”,界面下方,“輸出”部分,勾選“XML文檔文件(X)”,可以看到生成的路徑為絕對路徑,可以改為相對路徑,類似這樣,加2個點好,然后是WebApi項目目錄名,后面的xml文件名不變。

                  ..\MuXue.Zyiz.Template.WebApi\MuXue.Zyiz.Template.WebApi.xml

                  2、項目一般會有Model的實體層,配置跟上面類似,

                  ..\MuXue.Zyiz.Template.Domain\MuXue.Zyiz.Template.Domain.xml


                  第4步:生成解決方案,F5啟動即可。



                  有人發現,本地的swagger有字段說明,但是發布到服務器上,就沒有字段說明,原因是.netcore 3.1發布后,不會生成xml文件。解決方方法是,在vs2019項目里,剛剛我們設置成功生成的2個xml文件,右擊-“屬性”-“復制到輸出目錄”設置為“始終復制”即可。



                  隨時隨地學軟件編程-關注百度小程序和微信小程序
                  關于找一找教程網

                  本站文章僅代表作者觀點,不代表本站立場,所有文章非營利性免費分享。
                  本站提供了軟件編程、網站開發技術、服務器運維、人工智能等等IT技術文章,希望廣大程序員努力學習,讓我們用科技改變世界。
                  [.netcore 3.1高性能微服務架構:加入swagger接口文檔]http://www.yachtsalesaustralia.com/tech/detail-108663.html

                  贊(0)
                  關注微信小程序
                  程序員編程王-隨時隨地學編程

                  掃描二維碼或查找【程序員編程王】

                  可以隨時隨地學編程啦!

                  技術文章導航 更多>
                  国产在线拍揄自揄视频菠萝

                        1. <dd id="erndk"></dd>