文章摘要
该文章介绍了在C#中使用Swagger框架通过静态嵌套类 SwaggerExtend 实现的两种功能：一是通过静态方法 AddCustSwagger 配置 Swagger 描述文件，生成 Swagger 描述文档；二是通过静态方法 UseCustSwagger 配置 Swagger 中间件和 SwaggerUI，以便在应用程序中生成 Swagger 验证接口文档。该实现通过参数化的方式，支持自定义 Swagger 文档的生成路径、版本号、标题等，并且能够灵活配置 SwaggerUI 和 Swagger 中间的路径设置，以满足不同场景下的 Swagger 文档展示需求。
/// <summary>
/// Swagger 静态类
/// </summary>
public static class SwaggerExtend
{
/// <summary>
/// 添加服务: swagger
/// </summary>
/// <param name=”services”></param>
/// <returns></returns>
public static void AddCustSwagger(this IServiceCollection services)
{
var version=”V1.0″;
var apiName=”XXX系统”;
services.AddSwaggerGen(options=>
{
options.ResolveConflictingActions(apiDescriptions=> apiDescriptions.First());
options.SwaggerDoc(“system_v1″, new OpenApiInfo
{
Version=version,
Title=$”{apiName} API”,
Description=$”{apiName} {version} 接口服务”
});
// 获取应用程序所在目录
var basePath=Path.GetDirectoryName(typeof(SwaggerExtend).Assembly.Location);
var xmlPath=Path.Combine(basePath, “ProjectName.xml”);
// swagger界面默认只显示 方法&字段 注释，不显示 控制器注释
// 第二个参数为true， 则是controller的注释
//options.IncludeXmlComments(xmlPath);
options.IncludeXmlComments(xmlPath, true);
});
}
/// <summary>
/// 添加中间件: swagger
/// </summary>
/// <param name=”app”></param>
public static void UseCustSwagger(this IApplicationBuilder app)
{
app.UseSwagger();
app.UseSwaggerUI(options=>
{
options.SwaggerEndpoint(“/swagger/system_v1/swagger.json”, “系统API”);
// 默认路径为：/swagger/index.html
// 路由前缀 – 设置为空，可直接跳转到swagger页面：/index.html
// api测试可设置为空，部署时容易与前端路由冲突
options.RoutePrefix=string.Empty;
});
}
}