ASP.NET Core WebAPI构建时生成多环境定制化Swagger JSON咨询

没问题，我来一步步帮你搞定这个需求——既生成带环境和构建号的自定义命名Swagger JSON，又能根据环境调整JSON里的字段。

一、基础配置：动态生成Swagger文档信息 #

首先在你的Program.cs里配置Swagger，让它能根据环境变量动态调整文档内容和输出路径。这里我们会用到IWebHostEnvironment获取当前环境，同时通过环境变量传入构建号（比如BUILD_NUMBER）。

var builder = WebApplication.CreateBuilder(args);

// 添加Swagger服务
builder.Services.AddSwaggerGen(c =>
{
    // 获取环境信息
    var env = builder.Environment;
    // 从环境变量取构建号，本地调试默认设为"local"
    var buildNumber = Environment.GetEnvironmentVariable("BUILD_NUMBER") ?? "local";
    var appName = "YourAppName"; // 替换成你的应用实际名称

    // 动态设置文档核心信息，根据环境调整
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = $"Your API ({env.EnvironmentName})",
        Version = $"v1-{buildNumber}",
        Description = $"API documentation for {env.EnvironmentName} environment"
    });

    // 可选：根据环境配置API服务器地址
    c.AddServer(new OpenApiServer
    {
        Url = env.EnvironmentName switch
        {
            "Development" => "https://dev.yourdomain.com/api",
            "Demo" => "https://demo.yourdomain.com/api",
            "Integration" => "https://int.yourdomain.com/api",
            "Staging" => "https://staging.yourdomain.com/api",
            _ => "https://localhost:5001/api"
        }
    });

    // 加载XML注释（如果你的API有注释的话，可选）
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

var app = builder.Build();

// 构建阶段触发Swagger JSON生成（通过环境变量控制）
if (!string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GENERATE_SWAGGER")))
{
    using var scope = app.Services.CreateScope();
    var swaggerGenerator = scope.ServiceProvider.GetRequiredService<ISwaggerProvider>();
    var doc = swaggerGenerator.GetSwagger("v1");
    
    var envName = app.Environment.EnvironmentName.ToLower();
    // 映射环境名到你的命名规则后缀
    var envSuffix = envName switch
    {
        "development" => "dev",
        "demo" => "demo",
        "integration" => "int",
        "staging" => "staging",
        _ => "dev"
    };
    var fileName = $"swagger_{appName}_{envSuffix}_{buildNumber}.json";
    var outputPath = Path.Combine(Directory.GetCurrentDirectory(), "wwwroot", fileName);
    
    using var writer = new StreamWriter(outputPath);
    using var jsonWriter = new JsonTextWriter(writer);
    doc.SerializeAsV3(jsonWriter);
}

// 其他中间件配置（比如Swagger UI，本地调试用）
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.Run();

二、构建阶段批量生成多环境JSON文件 #

接下来在CI/CD脚本（比如GitHub Actions、Azure DevOps Pipeline，或者本地脚本）中，针对每个环境运行一次应用，触发Swagger JSON生成。

举个bash脚本的例子：

# 配置应用名称和构建号（构建号可以从CI/CD变量获取）
APP_NAME="YourAppName"
BUILD_NUMBER="$BUILD_ID" # 替换成你的CI/CD工具提供的构建号变量

# 遍历所有目标环境
environments=("Development" "Demo" "Integration" "Staging")
for env in "${environments[@]}"
do
    echo "开始生成${env}环境的Swagger JSON..."
    ASPNETCORE_ENVIRONMENT=$env BUILD_NUMBER=$BUILD_NUMBER GENERATE_SWAGGER=true dotnet run --no-launch-profile
done

运行完脚本后，你的wwwroot目录下就会生成4个完全符合命名规则的JSON文件了。

三、灵活修改JSON字段的补充方案 #

如果需要修改一些更个性化的字段（比如自定义扩展属性），除了在AddSwaggerGen里通过代码配置，还可以在生成JSON后用工具批量修改。比如用jq命令（适合Linux/macOS）：

# 修改dev环境JSON里的info.description字段
jq '.info.description = "开发环境API文档 - 仅限内部使用"' swagger_YourAppName_dev_123.json > temp.json && mv temp.json swagger_YourAppName_dev_123.json

不过更推荐用代码动态配置的方式，这样更可控，也能避免后续的文件修改操作。

注意事项 #

• 确保构建阶段运行应用时，能加载到必要的配置（比如数据库连接字符串，如果Swagger需要生成实体模型的话）；如果不需要数据库依赖，可以在生成Swagger时暂时禁用相关服务。
• 在CI/CD工具中，记得把生成的JSON文件作为构建产物保存，方便后续上传到Swagger UI或者API网关使用。

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