Swagger 2.0报错：同路径多GET接口不支持的解决问询

我之前调试API路由时也踩过这个一模一样的坑，这个错误的核心原因就是Swagger 2.0的硬性规则——它不允许同一个路径+同一个HTTP方法下存在多个API操作。哪怕你觉得已经更新了端点和路由，大概率是还有隐藏的重复项没排查到，下面是我亲测有效的解决步骤：

• 第一步：排查Controller里的重复Action
  先仔细检查你的DoorsController（或对应业务的Controller）里的GET方法，有没有两个方法的路由最终都指向了api/Doors/{OrganizationSys}。比如这种隐形重复：

  // 第一个明确指定了路由
  [HttpGet("api/Doors/{OrganizationSys}")]
  public IActionResult GetDoors(int OrganizationSys) { ... }
  
  // 第二个没加特性，但默认路由模板刚好匹配到同一个路径
  [HttpGet]
  public IActionResult GetDoorDetails(int OrganizationSys) { ... }
  

  解决办法：给每个GET方法设置唯一的路由模板，比如把第二个方法改成[HttpGet("api/Doors/{OrganizationSys}/details")]，确保路径完全不重复。

• 第二步：注意参数类型导致的隐形重复
  Swagger 2.0不会根据参数类型来区分路径，比如你有两个GET方法，一个参数是int OrganizationSys，另一个是string OrganizationSys，哪怕参数类型不同，Swagger还是会判定这是同一个路径的重复操作。
  解决办法：要么给其中一个方法修改路径（比如api/Doors/by-string/{OrganizationSys}），要么如果用的是Swashbuckle，可以配置Swagger来识别参数类型差异（不过改路径是更简单直接的方案）。

• 第三步：清理缓存并重启项目
  有时候修改路由后，Swagger的缓存或者项目的路由缓存没更新，导致它还在读取旧的路由配置。可以试试：

  • 完全重启你的API项目
  • 用浏览器无痕模式打开Swagger页面（或者手动清除浏览器缓存）
  • 如果是Swashbuckle，检查Startup.cs里的EnableSwagger配置，有没有硬编码的旧路由规则

• 第四步：检查全局路由前缀/Area配置
  如果你的项目配置了全局路由前缀（比如在Startup.cs里加了app.UseMvc(routes => routes.MapRoute("default", "api/{controller}/{action}/{id?}"))），同时又在Action上写了完整的api/Doors/...路由，可能会导致实际生成的路径重复。比如一个方法是全局前缀+Action默认路由，另一个是Action指定的完整路由，最终都指向同一个路径。
  解决办法：统一路由配置风格，要么全用全局前缀，要么全在Action上指定完整路径，不要混合使用。

• 特殊场景：用OperationId强制区分（不推荐）
  如果确实有特殊需求要保留同一个路径和方法，可以给每个方法指定唯一的OperationId，让Swagger能识别它们是不同的操作：

  [HttpGet("api/Doors/{OrganizationSys}")]
  [SwaggerOperation(OperationId = "GetDoorsByIntegerOrgId")]
  public IActionResult GetDoors(int OrganizationSys) { ... }
  
  [HttpGet("api/Doors/{OrganizationSys}")]
  [SwaggerOperation(OperationId = "GetDoorsByStringOrgId")]
  public IActionResult GetDoors(string OrganizationSys) { ... }
  

  注意：这种方法只能解决Swagger文档生成的问题，实际API路由还是会冲突（因为ASP.NET Core无法根据参数类型区分同一个路径的GET请求），所以优先推荐修改路径。

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