ASP MVC5+WebApi项目中Swashbuckle无法识别控制器求助

我之前也碰到过一模一样的情况——加了RoutePrefix后Swagger文档直接空了，大概率是属性路由配置或者Swashbuckle的设置没到位，给你几个排查和解决的步骤：

1. 先检查WebAPI的路由基础配置 #

首先确保你的WebApiConfig.cs里启用了属性路由，这是带RoutePrefix的控制器能被识别的前提：

public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        // 这行必须放在传统路由前面！启用属性路由
        config.MapHttpAttributeRoutes();

        // 传统路由（可选，保留也没问题）
        config.Routes.MapHttpRoute(
            name: "DefaultApi",
            routeTemplate: "api/{controller}/{id}",
            defaults: new { id = RouteParameter.Optional }
        );
    }
}

如果没加config.MapHttpAttributeRoutes()，属性路由完全不会生效，Swashbuckle自然找不到你的控制器。

2. 补全控制器的Action路由属性 #

你给控制器加了[RoutePrefix("api/v1/Test/Check")]，但里面的Action只加了HttpGet/HttpPost，没配对应的Route属性，Swashbuckle识别不到这些Action。补全后应该是这样：

[RoutePrefix("api/v1/Test/Check")]
public class TestController : ApiController
{
    // GET: api/v1/Test/Check
    [HttpGet]
    [Route("")] // 对应路由前缀的根路径
    public IEnumerable<string> Get()
    {
        return new string[] { "value1", "value2" };
    }

    // GET: api/v1/Test/Check/5
    [HttpGet]
    [Route("{id}")] // 带参数的路由模板
    public string Get(int id)
    {
        return "value";
    }

    // POST: api/v1/Test/Check
    [HttpPost]
    [Route("")]
    public void Post([FromBody]string value)
    {
        // 你的业务逻辑
    }
}

[Route("")]表示继承控制器的路由前缀，作为该Action的完整路由；[Route("{id}")]则是在前缀基础上追加参数路径。

3. 调整Swashbuckle的配置（SwaggerConfig.cs） #

打开项目里的SwaggerConfig.cs，确保开启了对属性路由的支持，同时可以加上XML注释提升文档可读性（可选但推荐）：

GlobalConfiguration.Configuration
    .EnableSwagger(c =>
    {
        // 允许Swashbuckle识别属性路由和Swagger注解
        c.EnableAnnotations();
        // 解决路由冲突（如果有多个Action匹配同一路由时）
        c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
        // 可选：加载XML注释文件，让文档显示接口说明
        c.IncludeXmlComments(() => 
        {
            var xmlPath = System.Web.HttpContext.Current.Server.MapPath("~/bin/YourProjectName.XML");
            return xmlPath;
        });
    })
    .EnableSwaggerUi(c =>
    {
        // 这里可以加UI相关的自定义配置，比如隐藏顶部的Swagger品牌链接
        // c.DisableValidator();
    });

注意：如果要加XML注释，需要在项目属性的“生成”选项卡里勾选“XML文档文件”，路径填bin\YourProjectName.XML。

4. 确认Swashbuckle包的版本 #

别装错包了！你的项目是ASP.NET MVC5（基于.NET Framework），要装的是NuGet包Swashbuckle（不是Swashbuckle.AspNetCore，那是给ASP.NET Core用的），推荐选5.x系列的版本，和.NET Framework 4.x兼容性更好。

5. 清理缓存重新生成 #

最后一步，清理解决方案，删除bin和obj文件夹，重新生成项目，再访问/swagger页面看看——有时候缓存会导致Swashbuckle没更新文档。

按照这些步骤走下来，你的控制器和接口应该就能正常显示在Swagger文档里了！

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