Swagger报POST api/v{version}/Employee路径方法冲突异常求助

抛出SwaggerGeneratorException: Conflicting method/path combination "POST api/v{version}/Employee" for actions的核心原因是Swagger扫描接口时，识别到两个HTTP请求方法、请求路径完全一致的接口，无法做唯一区分。
你当前的两个接口虽然标记了不同的[ApiVersion]特性，但路由模板中的{version}占位符没有和API版本特性做绑定，Swagger无法感知两个接口属于不同版本，会直接将两个接口解析为同一路由POST api/v{version}/Employee，触发路由冲突报错。

• 第一步：给路由添加API版本约束，绑定版本占位符
  在控制器或接口方法的路由特性中，给{version}占位符添加apiVersion约束，让框架能将路由段和[ApiVersion]特性关联，示例如下：

  // 控制器路由配置示例
  [ApiController]
  [Route("api/v{version:apiVersion}/[controller]")]
  public class EmployeeController : ControllerBase
  {
      [HttpPost]
      [ApiVersion("1.0")]
      public IActionResult SetEmployeeV1()
      { 
          // v1版本逻辑
      }
  
      [HttpPost]
      [ApiVersion("2.0")]
      public IActionResult SetEmployeeV2()
      {
          // v2版本逻辑             
      }
  }
  

• 第二步：配置Swagger支持多版本分组，避免路径冲突
  在服务配置阶段（Program.cs/Startup.cs）为每个API版本声明独立的Swagger文档，同时配置文档包含规则，让Swagger按版本将接口分组到对应文档中，核心配置示例：

  // 注册API版本控制服务
  builder.Services.AddApiVersioning(options =>
  {
      options.ReportApiVersions = true;
      options.AssumeDefaultVersionWhenUnspecified = true;
      options.DefaultApiVersion = new ApiVersion(1, 0);
  });
  
  // 注册Swagger生成器，配置多版本支持
  builder.Services.AddSwaggerGen(options =>
  {
      // 为每个版本定义独立的Swagger文档
      options.SwaggerDoc("v1", new OpenApiInfo { Title = "系统接口文档", Version = "1.0" });
      options.SwaggerDoc("v2", new OpenApiInfo { Title = "系统接口文档", Version = "2.0" });
  
      // 配置接口按版本归入对应文档，解决同路径多版本冲突
      options.DocInclusionPredicate((docName, apiDesc) =>
      {
          if (!apiDesc.TryGetMethodInfo(out MethodInfo methodInfo)) return false;
          // 扫描控制器、方法上的ApiVersion特性
          var controllerVersions = methodInfo.DeclaringType
              .GetCustomAttributes(true)
              .OfType<ApiVersionAttribute>()
              .SelectMany(attr => attr.Versions);
          var actionVersions = methodInfo
              .GetCustomAttributes(true)
              .OfType<ApiVersionAttribute>()
              .SelectMany(attr => attr.Versions);
          var allVersions = controllerVersions.Concat(actionVersions);
          // 匹配当前接口版本和文档版本
          return allVersions.Any(v => $"v{v.MajorVersion}" == docName);
      });
  });
  

• 第三步：排查重复路由声明
  检查两个接口方法、所属控制器上是否额外写死了重复的路径片段，确保除版本占位符外，没有其他重复的路由配置覆盖版本规则。

内容的提问来源于stack exchange，提问作者Sayed Mohammad Hossain Rouhani