如何为ASP.NET Core Web API的Areas控制器添加Swagger？

核心原因 #

默认情况下，Swagger只会自动识别根目录Controllers文件夹下、带[ApiController]特性且配置了路由的控制器，Areas目录下的控制器不在默认扫描范围内，需要手动调整配置。

具体解决步骤 #

1. 给Areas内的控制器补全必要特性 #

先检查Areas下的控制器是否加对了特性，这是Swagger识别的基础：

• 必须标记[ApiController]特性
• 结合区域配置正确路由，示例代码：

[ApiController]
[Area("你的区域名称")] // 替换成实际业务模块名，比如"Order"
[Route("api/[area]/v1/[controller]")]
public class OrderController : ControllerBase
{
    // 接口方法实现
}

2. 配置Swagger扫描所有目标程序集 #

在Program.cs的Swagger配置中，指定要扫描的程序集（如果所有控制器都在当前Host.web项目里，直接扫当前程序集即可）：

builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "你的API名称", Version = "v1" });
    
    // 扫描当前程序集中所有带ApiController特性的控制器
    var currentAssembly = typeof(Program).Assembly;
    // 可选：启用XML注释（需要先在项目生成设置里勾选XML文档文件）
    c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, $"{currentAssembly.GetName().Name}.xml"));
    
    // 明确指定扫描带ApiController特性的控制器
    c.SelectControllersWithAttribute<ApiControllerAttribute>();
});

3. 让Mvc识别Areas内的控制器 #

在Program.cs配置Mvc时，添加当前程序集作为应用部件，确保Areas内的控制器被Mvc发现，进而被Swagger识别：

builder.Services.AddControllers()
    .AddApplicationPart(typeof(Program).Assembly); // 把当前项目程序集加入Mvc的部件列表

如果Areas内的控制器用了区域路由，还可以给控制器加上[ApiExplorerSettings]特性，确保分组和SwaggerDoc对应：

[ApiController]
[Area("Order")]
[Route("api/order/v1/[controller]")]
[ApiExplorerSettings(GroupName = "v1")] // 和SwaggerDoc的"v1"分组对应
public class OrderController : ControllerBase
{
    // ...
}

4. 验证配置 #

重启项目后，访问SwaggerUI地址（一般是https://localhost:<端口号>/swagger），检查Areas内的控制器是否出现在接口列表里。

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