为何出现Swagger方法/路径组合冲突错误？

SwaggerGeneratorException: Conflicting method/path combination "GET Exercise" for actions - FitnessTracker.Controllers.ExerciseController.GetExerciseList (FitnessTracker),FitnessTracker.Controllers.ExerciseController.GetExerciseById (FitnessTracker). Actions require a unique method/path combination for Swagger/OpenAPI 3.0. Use ConflictingActionsResolver as a workaround

我原本以为Web API会从函数前缀（比如Get、Post）推断HTTP动词，只要函数名或参数列表唯一就行，但现在出现了上面的冲突错误。下面是我的控制器代码：

[ApiController]
[Route("[controller]")]
public class ExerciseController : ControllerBase
{
    private readonly IDL DL;
    private readonly ILogger<ExerciseController> logger;

    public ExerciseController(IDL dL, ILogger<ExerciseController> logger)
    {
        DL = dL;
        this.logger = logger;
    }

    [HttpGet(Name = "GetExerciseList")]
    [Route("api/[controller]/[action]")]
    public List<Exercise> GetExerciseList()
    {
        return DL.GetExerciseList();
    }

    [HttpGet(Name = "GetExerciseById")]
    [Route("api/[controller]/[action]")]
    public Exercise GetExerciseById(string exerciseId)
    {
        return DL.GetExerciseById(exerciseId);
    }
}

我也搞不懂属性里Name = "GetExerciseList"有啥用，感觉有点多余。为啥会出现冲突？这两个函数不管是名称还是参数列表都不一样啊。我试了好几种Route属性，都解决不了问题，包括：

[Route("api/[controller]/[action]")]
[Route("api/[Controller]/ExerciseList")]
[Route("api/Exercise/ExerciseList")]
[Route("RoutingSucks")]
[Route("ICanPutAnythingHereAndItMakesNoDifference")]

问题根源 #

1. 路由规则叠加混乱：你给控制器加了[Route("[controller]")]，同时又给每个Action单独加了[Route("api/[controller]/[action]")]，导致路由规则叠加冲突。Swagger解析时错误判定两个接口的GET + 路径组合重复，哪怕参数不同也不行——Swagger要求HTTP方法+路径必须是全局唯一的标识，参数不参与唯一性判定。
2. Name属性的作用：这个属性是给路由起别名，方便后续通过名称生成URL（比如用Url.RouteUrl调用），和路径匹配、Swagger识别完全无关，确实属于冗余配置。

解决办法 #

方法一：规范路由，确保路径唯一 #

去掉控制器级别的冗余路由，或者调整Action路由让路径明确区分：

[ApiController]
[Route("api/[controller]")] // 统一控制器路由前缀
public class ExerciseController : ControllerBase
{
    // ...构造函数不变

    // 路径：api/Exercise/list
    [HttpGet("list")]
    public List<Exercise> GetExerciseList()
    {
        return DL.GetExerciseList();
    }

    // 路径：api/Exercise/{exerciseId}
    [HttpGet("{exerciseId}")]
    public Exercise GetExerciseById(string exerciseId)
    {
        return DL.GetExerciseById(exerciseId);
    }
}

此时两个接口的GET+路径组合分别是GET api/Exercise/list和GET api/Exercise/{exerciseId}，完全唯一，Swagger可正常识别。

方法二：保留Action名称路由，避免叠加冲突 #

如果想用[action]自动生成路径，要确保控制器和Action的路由规则不叠加：

[ApiController]
[Route("api/[controller]")]
public class ExerciseController : ControllerBase
{
    // ...

    // 路径：api/Exercise/GetExerciseList
    [HttpGet("[action]")]
    public List<Exercise> GetExerciseList()
    {
        return DL.GetExerciseList();
    }

    // 路径：api/Exercise/GetExerciseById/{exerciseId}
    [HttpGet("[action]/{exerciseId}")]
    public Exercise GetExerciseById(string exerciseId)
    {
        return DL.GetExerciseById(exerciseId);
    }
}

这种方式下两个接口路径也完全唯一，冲突自然解决。

方法三：Swagger冲突临时兼容（不推荐） #

如果暂时不想改路由，可以在Swagger配置里添加冲突解析器（属于临时 workaround）：

builder.Services.AddSwaggerGen(c =>
{
    // 遇到冲突时取第一个接口描述
    c.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
});

但这个方法只是掩盖问题，不推荐长期使用，规范路由才是根本解决方式。

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