Swashbuckle.AspNetCore.CLI生成Swagger文档CI/CD环境异常处理咨询

下面是几个可行的解决方案，按需选择：

1. 拆分Swagger生成逻辑，跳过业务依赖加载 #

默认的dotnet swagger tofile命令需要启动完整应用，会触发Program.Main里的所有依赖加载逻辑。你可以在代码里判断当前是否是Swagger生成场景，只加载Swagger相关服务，跳过业务依赖：

var args = args;
// 判断是否是swagger tofile命令
var isGeneratingSwagger = args.Any(arg => arg.Contains("swagger tofile"));

var builder = WebApplication.CreateBuilder(args);

// 只在非Swagger生成场景加载业务依赖
if (!isGeneratingSwagger)
{
    builder.Services.AddDbContext<AppDbContext>(options => 
        options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));
    builder.Services.AddHttpClient<ThirdPartyApiService>();
    // 其他业务服务注册逻辑
}

// 始终加载Swagger配置
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API", Version = "v1" });
    // 其他Swagger配置，比如XML注释路径等
});

var app = builder.Build();

// 非Swagger场景才启动业务中间件
if (!isGeneratingSwagger)
{
    app.UseHttpsRedirection();
    app.UseAuthorization();
    app.MapControllers();
}

// 如果是Swagger生成场景，直接退出，避免启动完整应用
if (isGeneratingSwagger)
{
    return 0;
}

app.Run();

这样CI/CD环境执行命令时，应用会跳过所有业务依赖的加载，顺利生成Swagger文档。

2. 使用dotnet swagger generate命令（无需启动应用） #

Swashbuckle.AspNetCore提供了generate命令，它直接通过反射编译后的程序集生成Swagger文档，完全不需要启动应用，自然不会碰到依赖问题。命令格式如下：

dotnet swagger generate --output ./swagger.json --assembly ./bin/Release/net6.0/你的API程序集.dll --swaggerdoc v1

注意替换命令里的程序集路径和Swagger文档名称，确保API项目已经提前编译完成。

3. 为CI环境提供依赖的Mock实现 #

如果不想修改太多代码，可以在CI环境下注册依赖的假实现，让应用能正常启动但不依赖真实的外部服务：

// 通过环境变量判断是否是CI环境
var isCI = Environment.GetEnvironmentVariable("CI") == "true";

if (isCI)
{
    // 注册Mock服务
    builder.Services.AddScoped<IThirdPartyService, MockThirdPartyService>();
    // 使用内存数据库代替真实数据库
    builder.Services.AddDbContext<AppDbContext>(options => 
        options.UseInMemoryDatabase("MockCI_DB"));
}
else
{
    // 生产/本地环境使用真实依赖
    builder.Services.AddScoped<IThirdPartyService, RealThirdPartyService>();
    builder.Services.AddDbContext<AppDbContext>(options => 
        options.UseSqlServer(builder.Configuration.GetConnectionString("Default")));
}

CI环境启动应用时会用Mock依赖替代真实依赖，避免因外部服务不可用导致启动失败。

内容的提问来源于stack exchange，提问作者Andy Song