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 包

在程序包管理器控制台中输入如下代码

01	`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 = "123456789@qq.com"
            }
        });
    });
}

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
});