.NetCore WebApi——Swagger簡單配置

在前後端分離的大環境下，API介面文檔成為了前後端交流的一個重點。Swagger讓開發人員擺脫了寫介面文檔的痛苦。

官方網址：https://swagger.io/

在.Net Core WebApi中通過簡單配置即可使用這一強大的功能。

1.新建一個API的項目

選擇 API 項目

2.引入Swagger包。.Net Core 中支持兩個分別為Swashbuckle和NSwag。兩者的配置大同小異。這裡以Swashbuckle為例。

方式1：選擇工具——Nuget包管理——管理解決方案的Nuget包

搜索：Swashbuckle.AspNetCore  安裝即可

方式2：直接在程式包管理控制台輸入：Install-Package Swashbuckle.AspNetCore  回車即可安裝

安裝之後在項目的Nuget包中就可以看到了

3.配置Swagger中間件

   3.1 在Startup類ConfigureServices方法中添加Swagger服務並配置文檔信息

 public void ConfigureServices(IServiceCollection services)
        {
            // 註冊Swagger服務
            services.AddSwaggerGen(c =>
            {
                // 添加文檔信息
                c.SwaggerDoc("v1", new Info { Title = "CoreWebApi", Version = "v1" });
            });
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
        }

   3.2 在 Startup類Configure 方法中，啟用中間件為生成的 JSON 文檔和 Swagger UI 提供服務

 public void Configure(IApplicationBuilder app, IHostingEnvironment env)
        {
            if (env.IsDevelopment())
            {
                app.UseDeveloperExceptionPage();
            }
            else
            {
                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
                app.UseHsts();
            }
      
            app.UseHttpsRedirection();
            // 啟用Swagger中間件
            app.UseSwagger();

            // 配置SwaggerUI
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");
               
            });
            app.UseMvc();
        }

 右鍵項目屬性，將URL地址固定到某個埠

然後將啟動項設置為當前項目，然後啟動。

在根目錄目前是沒有東西的。下一步將在根目錄處使用SwaggerUI

將RoutePrefix屬性設置為空

    app.UseHttpsRedirection();
            // 啟用Swagger中間件
            app.UseSwagger();

            // 配置SwaggerUI
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "CoreWebApi");
                c.RoutePrefix = string.Empty;
            });

再次啟動項目，SwaggerUI文檔成功顯示出來。整體簡潔大方。

 API的信息說明：傳遞給AddSwaggerGen（）的方法可配置一些API的信息說明以及作者信息等，來展示到UI頁面。修改AddSwaggerGen（）方法。 

// 註冊Swagger服務
            services.AddSwaggerGen(c =>
            {
                // 添加文檔信息
                c.SwaggerDoc("v1", new Info
                {
                    Title = "CoreWebApi",
                    Version = "v1",
                    Description="ASP.NET CORE WebApi",
                    Contact=new Contact
                    {
                        Name="Jee",
                        Email="[email protected]"
                    }
                });
            });

展示對應的信息

 4.啟用XML註釋。上邊的效果只有一個簡單說明，並沒有我們在後臺寫的註釋。啟用XML註釋之後可以輕鬆映射到UI界面方便前端開發人員理解。

右鍵當前項目——編輯****.csproj 的文件  在PropertyGroup標簽組中添加如下兩條

<GenerateDocumentationFile>true</GenerateDocumentationFile> <NoWarn>$(NoWarn);1591</NoWarn>

這兩句的大概意思就是啟用XML註釋，並忽略未寫註釋的警告。不添加1591如果某個方法未寫 "///"各式的註釋，vs會有警示的消息。

之後AddSwaggerGen（）方法中讀取xml文件路徑並啟用

       // 註冊Swagger服務
            services.AddSwaggerGen(c =>
            {
                // 添加文檔信息
                c.SwaggerDoc("v1", new Info
                {
                    Title = "CoreWebApi",
                    Version = "v1",
                    Description="ASP.NET CORE WebApi",
                    Contact=new Contact
                    {
                        Name="Jee",
                        Email="[email protected]"
                    }
                });
                // 使用反射獲取xml文件。並構造出文件的路徑
                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                // 啟用xml註釋. 該方法第二個參數啟用控制器的註釋，預設為false.
                c.IncludeXmlComments(xmlPath,true);
            });

再次啟動項目，可以看到寫的註釋全部都映射出來了

Text類的返回值也可以映射出來

Models文件夾中的實體也可以映射在介面下方

 總結：   在.net core中配置swagger非常之快速。但這也是堪堪達到可以用的程度，算是入門級別吧。

源碼：GitHub

https://github.com/xiaoMaPrincess/Asp.NetCore-WebApi