.NET源代码生成器创建的控制器无法在Swagger中显示及调用

核心排查与修复步骤 #

1. 确保主项目正确引用生成器输出的程序集 #

• 检查.NET 7主API项目是否添加了对源代码生成器项目的项目引用，且引用的Copy Local属性设置为True，保证生成的程序集能被主项目加载。

2. 显式配置控制器发现范围 #

.NET默认仅扫描启动项目和直接引用项目的控制器，需手动指定扫描生成器输出的程序集：
在Program.cs中修改控制器服务配置：

builder.Services.AddControllers()
    .AddApplicationPart(typeof(ManufacturerController).Assembly);

如果无法直接引用类型，可通过程序集名称加载：

var generatedAssembly = Assembly.Load("Company.Api.Controllers.Generated");
builder.Services.AddControllers()
    .AddApplicationPart(generatedAssembly);

3. 验证路由配置正确性 #

基类路由[Route("api/[Controller]/[action]")]结合[HttpGet("{id}")]，最终有效路由为api/Manufacturer/GetManufacturerById/{id}，确认Postman调用路径是否匹配。
也可尝试给控制器显式添加路由特性，简化路由规则：

[Route("api/[controller]")]
public partial class ManufacturerController : ApiController
{
    [HttpGet("{id}")]
    // ... 原有方法代码
}

此时路由变为api/Manufacturer/{id}，避免[action]可能引发的路由解析问题。

4. 检查生成代码的有效性 #

• 确认生成的控制器代码是public partial class，无语法错误，继承关系正确（ApiController派生自ControllerBase）。
• 确保生成的代码没有被标记为抽象类，且命名空间与主项目控制器的命名空间一致或被框架扫描覆盖。

5. 配置Swagger扫描生成程序集 #

让Swagger识别生成的API，需在AddSwaggerGen中添加程序集扫描逻辑：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "API文档", Version = "v1" });
    
    // 加载生成程序集的XML注释（若生成了注释文件）
    var xmlFileName = $"{typeof(ManufacturerController).Assembly.GetName().Name}.xml";
    var xmlFilePath = Path.Combine(AppContext.BaseDirectory, xmlFileName);
    if (File.Exists(xmlFilePath))
    {
        c.IncludeXmlComments(xmlFilePath);
    }
    
    // 确保所有API都被包含到Swagger文档中
    c.DocInclusionPredicate((docName, apiDesc) => true);
});

6. 确认控制器符合识别规则 #

• 控制器类必须是public访问级别，非抽象类，且继承自ControllerBase或其派生类。
• 方法上的[HttpGet]等HTTP特性必须正确配置，无冲突或错误。

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