ASP.NET Core WebApi 中配置 Swagger

在前后端分離開發中，配置Swagger 可以免寫接口文檔，大大減少工作量，Swagger 簡潔高效，官網地址：https://swagger.io/，本篇博客介紹如何在.NET Core WebApi 中配置 Swagger

官方教程：https://docs.microsoft.com/zh-cn/aspnet/core/tutorials/getting-started-with-swashbuckle?view=aspnetcore-3.1&tabs=visual-studio

1、引入Swagger包

NuGet地址：https://www.nuget.org/packages

在NuGet中搜索 Swashbuckle.AspNetCore 找到 Swagger 包

在程序包管理器控制台中輸入如下代碼

Install-Package Swashbuckle.AspNetCore -Version 5.3.3

在依賴項中出現 Swashbuckle.AspNetCore 表示添加成功

2、配置Swagger中間件

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

public void ConfigureServices(IServiceCollection services)
{
    // 注冊Swagger服務
    services.AddSwaggerGen(c =>
    {
        // 添加文檔信息
        c.SwaggerDoc("v1", new OpenApiInfo
        {
            Title = "TestWebApi",
            Version = "v1",
            Description = "測試API",
            Contact = new OpenApiContact
            {
                Name = "Kebele8",
                Email = "[e-mail]"
            }
        });
    });
}

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

public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }
    app.UseHttpsRedirection();
    // 啟用Swagger中間件
    app.UseSwagger();
    // 配置SwaggerUI
    app.UseSwaggerUI(c =>
    {
        c.SwaggerEndpoint("/swagger/v1/swagger.json", "TestWebApi");
        c.RoutePrefix = string.Empty; //路由前綴設置為空
    });
    app.UseMvc();
}

3、顯示XML注釋

3.1、使用XML注釋

啟用XML注釋之后可以輕松映射到UI界面方便前端開發人員理解

右鍵當前項目，編輯 .csproj 文件，在PropertyGroup標簽組中添加如下代碼：

<!--啟用XML注釋，並忽略未寫注釋的警告-->
<GenerateDocumentationFile>true</GenerateDocumentationFile>
<!--不添加1591如果某個方法未寫 "///"各式的注釋，會有警示的消息-->
<NoWarn>$(NoWarn);1591</NoWarn>

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

services.AddSwaggerGen(c =>
{
    #region 讀取xml信息
    // 使用反射獲取xml文件，並構造出文件的路徑
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    // 啟用xml注釋，該方法第二個參數啟用控制器的注釋，默認為false.
    c.IncludeXmlComments(xmlPath, true);
    #endregion
});

3.3、配置啟動地址

右鍵項目→調試，設置啟動瀏覽器路徑，復制 應用URL 到 啟動瀏覽器路徑

運行，效果圖如下：

請求接口顯示如下：

model也會顯示在下方

End！