.NET 6中Swashbuckle.AspNetCore.Cli结合SwaggerHostFactory生成swagger.json异常

首先明确：Swashbuckle.AspNetCore.Cli在.NET 6中完全支持SwaggerHostFactory，你遇到的paths和components为空问题，本质是配置不符合.NET 6的主机启动逻辑导致的。以下是具体排查和配置步骤：

一、确保项目依赖版本匹配 #

项目中需引入对应.NET 6版本的Swashbuckle包，版本建议统一（如6.x系列），避免版本不兼容。示例项目文件配置：

<Project Sdk="Microsoft.NET.Sdk.Web">
  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
    <PackageReference Include="Swashbuckle.AspNetCore.Cli" Version="6.4.0">
      <PrivateAssets>all</PrivateAssets>
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
    </PackageReference>
  </ItemGroup>
</Project>

二、正确实现SwaggerHostFactory #

.NET 6采用WebApplicationBuilder替代旧版IWebHostBuilder，Factory类需严格遵循这一启动逻辑，确保Swagger所需服务被正确注册：

1. 控制器API场景 #

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace DemoWebApi;

public class SwaggerHostFactory
{
    public static IHost CreateHost(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // 必须添加控制器服务，否则Swagger无法发现接口
        builder.Services.AddControllers();

        // 配置SwaggerGen，与运行时配置保持一致
        builder.Services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new() { Title = "DemoWebApi", Version = "v1" });
            // 若需包含XML注释，取消以下注释并确保项目已启用XML文档生成
            // var xmlPath = Path.Combine(AppContext.BaseDirectory, $"{typeof(SwaggerHostFactory).Assembly.GetName().Name}.xml");
            // c.IncludeXmlComments(xmlPath);
        });

        var app = builder.Build();
        // CLI仅需生成文档，无需启用Swagger中间件（UseSwagger/UseSwaggerUI）
        return app.Services.GetRequiredService<IHost>();
    }
}

2. 最小API场景 #

最小API需额外注册AddEndpointsApiExplorer，否则Swagger无法识别端点：

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

namespace DemoMinimalApi;

public class SwaggerHostFactory
{
    public static IHost CreateHost(string[] args)
    {
        var builder = WebApplication.CreateBuilder(args);

        // 最小API必须添加此服务，用于端点发现
        builder.Services.AddEndpointsApiExplorer();
        builder.Services.AddSwaggerGen(c =>
        {
            c.SwaggerDoc("v1", new() { Title = "DemoMinimalApi", Version = "v1" });
        });

        var app = builder.Build();
        // 注册最小API端点（需与运行时代码一致）
        app.MapGet("/api/hello", () => "Hello World!")
           .WithName("GetHello")
           .WithOpenApi();

        return app.Services.GetRequiredService<IHost>();
    }
}

三、正确执行CLI生成命令 #

执行命令前需确保项目已构建（dotnet build），命令需指定完整的Factory类名（含命名空间）和静态方法名：

# 针对Debug构建的项目
dotnet swagger tofile --output swagger.json --factory DemoWebApi.SwaggerHostFactory CreateHost bin/Debug/net6.0/DemoWebApi.dll v1

# 针对Release发布的项目
dotnet swagger tofile --output swagger.json --factory DemoWebApi.SwaggerHostFactory CreateHost bin/Release/net6.0/publish/DemoWebApi.dll v1

注意：命令末尾的v1需与AddSwaggerGen中定义的文档版本一致。

四、空paths/components的常见排查点 #

• 未注册AddControllers()或AddEndpointsApiExplorer()，导致Swagger无法发现API；
• Factory类中的服务配置与运行时不一致（如遗漏了控制器、端点注册）；
• CLI命令中指定的文档版本与SwaggerDoc定义的版本不匹配；
• 使用了未更新的旧dll文件，需重新构建项目后再执行CLI命令。

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