Swashbuckle.AspNetCore 在 Azure Pipeline 中生成 Swagger 文档的最佳实践

核心问题分析

在 ASP.NET Core Web API 项目中，使用 Swashbuckle.AspNetCore.Cli 工具生成 Swagger 文档时，许多开发者会遇到一个常见问题：当在 CI/CD 流水线（如 Azure DevOps）中执行 dotnet swagger tofile 命令时，应用程序会实际启动并尝试加载配置文件、连接数据库等，这可能导致构建过程失败或不必要的资源消耗。

技术原理剖析

Swashbuckle.AspNetCore.Cli 工具生成 OpenAPI 文档的本质是通过反射加载应用程序集，并实际运行应用程序来收集 API 元数据。这与开发环境中通过浏览器访问 /swagger 端点类似，都需要应用程序运行起来才能生成文档。

解决方案

1. 环境感知配置

在 Program.cs 或 Startup.cs 中，可以通过环境变量判断当前是否为文档生成模式：

var isSwaggerGeneration = Environment.GetEnvironmentVariable("SWAGGER_GENERATION") == "true";

if (!isSwaggerGeneration)
{
    // 正常的数据库连接、后台服务等初始化代码
    app.UseAuthentication();
    app.UseAuthorization();
    // 其他中间件
}

2. 条件化配置加载

修改配置加载逻辑，避免在文档生成时加载敏感或不必要的配置：

IConfiguration Configuration = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") ?? "Production"}.json", optional: true)
    .AddEnvironmentVariables()
    .Build();

if (Environment.GetEnvironmentVariable("SWAGGER_GENERATION") != "true")
{
    // 添加其他配置源，如数据库连接字符串等
}

3. Azure Pipeline 任务优化

在 Azure Pipeline 中，可以这样配置生成任务：

- task: CmdLine@2
  displayName: 'Generate Swagger'
  inputs:
    script: |
      dotnet new tool-manifest
      dotnet tool install --version 6.5.0 Swashbuckle.AspNetCore.Cli
      cd Api
      set SWAGGER_GENERATION=true
      set ASPNETCORE_ENVIRONMENT=Development
      dotnet swagger tofile --output $(Build.ArtifactStagingDirectory)/swagger.json $(System.DefaultWorkingDirectory)/src/Api/bin/Release/net8.0/Api.dll v1
  workingDirectory: '${{ parameters.workingDirectory }}'

高级技巧

轻量级启动配置

对于大型项目，可以考虑创建一个专门用于文档生成的轻量级启动配置：

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureWebHostDefaults(webBuilder =>
        {
            if (Environment.GetEnvironmentVariable("SWAGGER_GENERATION") == "true")
            {
                webBuilder.UseStartup<SwaggerOnlyStartup>();
            }
            else
            {
                webBuilder.UseStartup<ProductionStartup>();
            }
        });

其中 SwaggerOnlyStartup 只包含生成文档所需的最小功能集。

内存数据库替代

如果文档生成确实需要数据库访问，可以考虑使用内存数据库或模拟服务：

services.AddDbContext<ApplicationDbContext>(options =>
{
    if (Environment.GetEnvironmentVariable("SWAGGER_GENERATION") == "true")
    {
        options.UseInMemoryDatabase("SwaggerGeneration");
    }
    else
    {
        options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"));
    }
});

总结

在 CI/CD 环境中生成 Swagger 文档时，关键在于理解应用程序需要运行才能生成文档这一基本原理。通过环境变量控制应用程序行为、创建轻量级配置和使用替代服务，可以确保文档生成过程既高效又不会影响生产环境。这些技术不仅适用于 Azure DevOps，也可以应用于其他 CI/CD 系统和本地开发环境。