此博客是基于 asp.net core web api(.net core3.1)框架进行操作的。

一、安装Swagger包

在 NuGet程序包管理中安装下面的两个包：

swagger包：Swashbuckle.AspNetCore

swagger包过滤器：Swashbuckle.AspNetCore.Filters

二、swagger注册

在 Startup.cs文件的 ConfigureServices方法中进行 swagger注册。

#region swagger注入
services.AddSwaggerGen(c =>
{
    #region 添加文档信息   
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "aspNetCURD",
        Version = "v1",
        Description = "RESTful API"
    });
    #endregion

    #region 添加 Controller注释
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";  // 获取 项目名 + .xml 的文件
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile); // 文件 path
    c.IncludeXmlComments(xmlPath); // 添加 Controller注释
    #endregion

    #region 添加 swagger小锁  不需要授权的可以不要小锁
    var openApiSecurity = new OpenApiSecurityScheme
    {
        Description = "JWT认证授权，使用直接在下框中输入Bearer {token}（注意两者之间是一个空格）\"",
        Name = "Authorization",  //jwt 默认参数名称
        In = ParameterLocation.Header,  //jwt默认存放Authorization信息的位置（请求头）
        Type = SecuritySchemeType.ApiKey
    };

    c.AddSecurityDefinition("oauth2", openApiSecurity);
    c.OperationFilter<AddResponseHeadersFilter>();
    c.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();
    c.OperationFilter<SecurityRequirementsOperationFilter>();
    #endregion

});
#endregion

三、swagger 注入管道

在 app.UseRouting() 之后，app.UseEndpoints() 之前，将swagger注入管道。

app.UseRouting();

#region swagger管道注入
// 启用Swagger中间件
app.UseSwagger();

// 配置SwaggerUI
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "aspNetCURD");
    c.RoutePrefix = string.Empty; //路由前缀设置为空
});
#endregion

四、在项目的属性中添加 .xml路径

打开项目的属性，找到 生成/输出，在 "XML文档文件路径" 处配置上 xml路径。

XML文档文件路径为：项目名称 + .xml

五、最后效果

（1）没有使用授权小锁时

（2）使用了授权小锁后

#若有错误或不足，欢迎大佬斧正。