如何在ASP.NET Core中编程生成Swagger YAML（无需启动HTTP服务）

如果你不想启动Web服务，直接在命令行/CI流程里生成Swagger YAML，有两种靠谱的实现方式：

方式一：用官方Swashbuckle命令行工具（推荐，无需修改代码） #

Swashbuckle.AspNetCore.Cli是官方提供的命令行工具，专门用来生成Swagger文档，不需要启动Web应用。

1. 安装工具 #

• 全局安装（适合本地测试）：

  dotnet tool install -g Swashbuckle.AspNetCore.Cli
  

• 本地工具安装（适合CI/CD，避免环境依赖）：
  先在项目根目录初始化工具清单：

  dotnet new tool-manifest
  

  再安装工具（配置会写入.config/dotnet-tools.json）：

  dotnet tool install Swashbuckle.AspNetCore.Cli
  

2. 生成YAML文件 #

先编译你的项目，然后用工具指向编译后的DLL生成文档：

# 替换为你的项目DLL路径和Swagger文档版本（比如v1）
dotnet swagger tofile --yaml --output swagger.yaml bin/Release/net6.0/MyApi.dll v1

在CI流程里，标准步骤可以是：

1. 恢复工具：dotnet tool restore
2. 编译发布：dotnet publish -c Release -o publish
3. 生成YAML：dotnet swagger tofile --yaml --output swagger.yaml publish/MyApi.dll v1

方式二：添加自定义命令行参数（通过dotnet run触发） #

如果一定要通过dotnet run加参数的方式生成，可以修改Program.cs，让应用检测到特定参数时直接生成文档并退出，不启动Web服务。

修改后的Program.cs示例：

var builder = WebApplication.CreateBuilder(args);

// 检测是否有生成Swagger的命令参数
if (args.Contains("generate_swagger_yaml"))
{
    // 复用你现有的Swagger配置
    builder.Services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new() { Title = "MyApi", Version = "v1" });
        // 这里添加你的其他Swagger配置，比如注释文件路径等
    });

    var app = builder.Build();

    // 获取Swagger文档并输出YAML到控制台
    var swaggerProvider = app.Services.GetRequiredService<ISwaggerProvider>();
    var swaggerDoc = swaggerProvider.GetSwagger("v1");
    var yamlWriter = new Microsoft.OpenApi.Writers.OpenApiYamlWriter(Console.OpenStandardOutput());
    swaggerDoc.SerializeAsV3(yamlWriter);

    return; // 直接退出，不启动Web服务
}

// 原有Web服务启动逻辑
builder.Services.AddControllers();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = "MyApi", Version = "v1" });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

然后执行命令生成（注意--用来传递参数给你的应用）：

dotnet run -- generate_swagger_yaml > swagger.yaml

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