Swagger无法识别Web API 2控制器端点问题求助

我原本有一批控制器及端点，在Swagger中显示正常，后来发现这些控制器使用的是MVC而非Web API 2。

原控制器声明形式：

[ApiController]
public class myController : ControllerBase...

[HttpGet("routeName")]
public async Task<IActionResult> .....

修改为Web API 2形式后：

[RoutePrefix("[my]")]
public class myController : ApiController

[HttpGet]
[Route("myroute")]
public async Task<IHttpActionResult>......

修改后这些端点不再显示在Swagger中，我的program.cs中Swagger配置如下：

.....
builder.Services.AddSwaggerGen();
.....
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}
app.MapControllers();

问题原因 #

• 框架兼容性不匹配：你当前用的是ASP.NET Core的Swagger配置（AddSwaggerGen、MapControllers），但ApiController、RoutePrefix是ASP.NET Web API 2（基于.NET Framework）的专属特性，ASP.NET Core并不原生支持这些旧特性，导致Swagger无法扫描到对应的端点。
• 路由系统差异：ASP.NET Core的路由机制和Web API 2完全不同，RoutePrefix在ASP.NET Core中对应控制器级别的[Route]特性，Web API 2的路由规则无法被ASP.NET Core的路由中间件解析，自然不会被Swagger捕获。
• 控制器基类识别问题：Swagger默认只会扫描继承自ASP.NET Core原生控制器基类（ControllerBase/Controller）的类型，Web API 2的ApiController基类不在其扫描范围内。

解决办法 #

方案1：改用ASP.NET Core Web API规范（推荐） #

如果你的项目是ASP.NET Core，没必要强行套用Web API 2的写法，直接调整为ASP.NET Core的标准写法即可：

// 用[Route]替代Web API 2的RoutePrefix，控制器级路由
[Route("[controller]")]
[ApiController]
public class myController : ControllerBase
{
    // 动作级路由，完整路由为 /my/myroute
    [HttpGet("myroute")]
    public async Task<IActionResult> MyAction()
    {
        // 业务逻辑实现
    }
}

调整后Swagger就能正常识别并展示端点，同时能享受ASP.NET Core的原生支持。

方案2：添加Web API 2兼容包（仅适用于混合框架场景） #

如果必须保留Web API 2的写法，需要安装针对Web API 2的Swagger包并单独配置：

1. 安装NuGet包：Swashbuckle.AspNetWebApi（注意这是Web API 2专属的Swagger包，和ASP.NET Core的Swashbuckle.AspNetCore不是同一个）
2. 在Web API 2的启动配置中（通常是Global.asax）添加Swagger配置：

   protected void Application_Start()
   {
       GlobalConfiguration.Configure(WebApiConfig.Register);
       // 配置Web API 2的Swagger
       GlobalConfiguration.Configuration.EnableSwagger(c =>
       {
           c.SingleApiVersion("v1", "My API");
       }).EnableSwaggerUi();
   }
   

   这种方式仅适用于同时存在ASP.NET Core和Web API 2的混合项目，纯ASP.NET Core项目不推荐使用，会增加配置复杂度。

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