【C#.NET】Web API项目Swagger配置扩展

版本控制

注意Swagger的配置，确保每个API版本都有对应的文档描述，否则Swagger UI可能不会正确显示不同版本。可能需要使用AddSwaggerGen的多次调用，或者使用循环来动态添加各个版本的文档。

创建版本控制枚举

ApiVersions.cs

namespace Downey.Books.WebApi.SwaggerExt
{
    public enum ApiVersions
    {
        V1,
        V2,
        V3,
        V4,
        V5
    }
}

添加版本控制

#region 版本控制
typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
{
	option.SwaggerDoc(version, new OpenApiInfo()
	{
		Title = $"Downey Api文档",
		Version = version,
		Description = $"通用版本的CoreApi版本{version}"
	});
});
#endregion

调用版本控制

app.UseSwagger();
app.UseSwaggerUI(option => 
{
    foreach(string version in typeof(ApiVersions).GetEnumNames())
    {
        option.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"Downey 【{version}】版本");
    }
});

在控制器前添加版本标注

    /// <summary>
    /// 天气预报控制器
    /// </summary>
    [ApiController]
    [Route("[controller]")]
    [ApiExplorerSettings(IgnoreApi = false,GroupName = nameof(ApiVersions.V1))]
    public class WeatherForecastController : ControllerBase
    {
    	...
    }

案例展现

Token传值

添加token传值

#region 支持token传值
{
    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
    {
        Description = "请输入token,格式为 Bearer xxxxxx（注意中间必须有空格）",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Type = SecuritySchemeType.ApiKey,
        BearerFormat = "JWT",
        Scheme = "Bearer"
    });
}
#endregion

添加安全要求

	//添加安全要求
    option.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference()
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] { }
        }
    });

案例演示

Swagger升级扩展

在C#中，可以通过扩展方法和扩展属性来向现有的类添加新的方法和属性。扩展方法允许我们像调用实例方法一样调用它们，而扩展属性允许我们像使用普通属性一样使用它们。

this扩展

1. 创建一个静态类，并将其标记为static。
2. 在该类中创建一个静态方法，该方法将是我们要添加到现有类的扩展方法。方法的第一个参数必须使用this关键字标记，并且指定要扩展的类的类型。这个参数表示我们使用扩展方法的实例。
3. 对于扩展属性，我们可以通过创建一个静态类和一个静态方法来模拟扩展属性的行为。在方法内部，可以通过方法的名称和参数列表来实现属性的访问和值的返回。

完整代码

using Microsoft.OpenApi.Models;

namespace Downey.Books.WebApi.Utility.SwaggerExt
{
    /// <summary>
    /// Swagger扩展
    /// </summary>
    public static class CustomSwaggerExt
    {
        /// <summary>
        /// 配置Swagger
        /// </summary>
        /// <param name="services"></param>
        public static void AddSwaggerExt(this IServiceCollection services)
        {
            services.AddEndpointsApiExplorer();
            services.AddSwaggerGen(option =>
            {
                #region 支持注释
                // xml文档绝对路径--读取控制器api生成的xml文件
                var file = Path.Combine(AppContext.BaseDirectory, "Downey.Books.WebApi.xml");
                // true : 显示控制器层注释
                option.IncludeXmlComments(file, true);
                // 对action的名称进行排序
                option.OrderActionsBy(o => o.RelativePath);
                #endregion

                #region 版本控制
                typeof(ApiVersions).GetEnumNames().ToList().ForEach(version =>
                {
                    option.SwaggerDoc(version, new OpenApiInfo()
                    {
                        Title = $"Downey Api文档",
                        Version = version,
                        Description = $"通用版本的CoreApi版本{version}"
                    });
                });
                #endregion

                #region 支持token传值
                {
                    option.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme()
                    {
                        Description = "请输入token,格式为 Bearer xxxxxx（注意中间必须有空格）",
                        Name = "Authorization",
                        In = ParameterLocation.Header,
                        Type = SecuritySchemeType.ApiKey,
                        BearerFormat = "JWT",
                        Scheme = "Bearer"
                    });

                    //添加安全要求
                    option.AddSecurityRequirement(new OpenApiSecurityRequirement
                    {
                        {
                            new OpenApiSecurityScheme
                            {
                                Reference = new OpenApiReference()
                                {
                                    Type = ReferenceType.SecurityScheme,
                                    Id = "Bearer"
                                }
                            },
                            new string[] { }
                        }
                    });
                }
                #endregion

            });
        }
        /// <summary>
        /// 中间件生效
        /// </summary>
        /// <param name="app"></param>
        public static void UseSwaggerExt(this WebApplication app)
        {
            app.UseSwagger();
            app.UseSwaggerUI(option =>
            {
                foreach (string version in typeof(ApiVersions).GetEnumNames())
                {
                    option.SwaggerEndpoint($"/swagger/{version}/swagger.json", $"Downey 【{version}】版本");
                }
            });
        }
    }
}

使用扩展

#region 配置Swagger
//CustomSwaggerExt.AddSwaggerExt(builder.Services);
builder.Services.AddSwaggerExt();
#endregion

var app = builder.Build();
// Configure the HTTP request pipeline.
if (app.Environment.IsDevelopment())
{
	#region 使用Swagger
	//CustomSwaggerExt.UseSwaggerExt(app);
	app.UseSwaggerUI();
	#endregion
}