ASP.Net Core中使用Swagger
我們先簡單介紹下什麼是Swagger,主要是用來幹嘛??
在Swagger誕生之前,我們通常在開發介面的過程中,需要前後端共同維護一個介面文檔,然後大家按照介面文檔的規範進行對接。介面文檔儼然成了介面開發過程中不可或缺的一部分,然而對於大部分喜歡敲程式碼的同志們來說,寫文檔簡直頭疼,並且一般項目後期往往會由於疏忽未能及時更新文檔,導致程式碼和介面文檔不一致,這中間就有點道不清說不明了。
正是在這種大環境下,Swagger及時出現,解放了前後端開發人員對介面文檔的維護壓力。Swagger實際上就是一個自動生成規範介面文檔的工具,由服務端設計人員調用,我們只需要按照它的格式要求在程式碼中添加註釋即可。
好了,下面我們開始步入正題,如何快速搭建Swagger項目。
首先,我們需要添加.NetCore Web API應用程式。
然後,在項目中添加如下Nuget程式包。
添加Swagger引用之後,在項目中註冊並使用Swagger.
首先,註冊服務。
1 public void ConfigureServices(IServiceCollection services) 2 { 3 services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2); 4 //註冊Swagger服務 5 services.AddSwaggerGen(s => 6 { 7 //基本資訊配置 8 s.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo 9 { 10 Version = "v1", 11 Title = "個人測試", 12 Description = "僅供測試使用", 13 Contact = new Microsoft.OpenApi.Models.OpenApiContact { Email = "[email protected]" } 14 }); 15 //包含應用程式對應的Swagger xml文檔 16 var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml"; 17 var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); 18 s.IncludeXmlComments(xmlPath); 19 }); 20 }
對於XML文檔,我們還需要在生成時指定xml輸出路徑。我這裡是指定的項目根目錄。這裡有個禁止顯示警告配置:添加了1591(用於解決未添加xml說明的警告)
然後,我們添加Swagger中間件。
1 public void Configure(IApplicationBuilder app, IHostingEnvironment env) 2 { 3 if (env.IsDevelopment()) 4 { 5 app.UseDeveloperExceptionPage(); 6 } 7 else 8 { 9 // The default HSTS value is 30 days. You may want to change this for production scenarios, see //aka.ms/aspnetcore-hsts. 10 app.UseHsts(); 11 } 12 app.UseHttpsRedirection(); 13 app.UseMvc(); 14 //使用Swagger 15 app.UseSwagger(); 16 app.UseSwaggerUI(s => 17 { 18 //指定json文件 19 s.SwaggerEndpoint("/swagger/v1/swagger.json", "My API"); 20 //默認前綴swagger 此處去掉前綴 直接根目錄訪問 21 s.RoutePrefix = string.Empty; 22 }); 23 }
這裡有個地方大家需要注意下:s.SwaggerEndpoint(“/swagger/v1/swagger.json”, “My API”);指定json文件url的時候,url裡面的v1需要和服務註冊時:s.SwaggerDoc(“v1”, “”)這裡的v1對應一致。
最後,我們只需要在啟動項目,在瀏覽器中輸入URL://localhost:5001/index.html 埠以項目實際啟動的埠為準.
大家可以看到默認的介面方法中:
這裡的「Get方式獲取」就是我們在項目介面方法體上添加的xml注釋說明。
項目搭建成功啦!!!文中如有描述不對的地方,歡迎各位小夥伴前來交流。