ASP.NET Core配置同路由不同Action触发Swagger报错问题咨询

ASP.NET Core原生支持同URL路径、同HTTP方法的路由配置，可通过请求的Accept MIME类型区分不同处理逻辑。你遇到的报错是Swagger/OpenAPI 3.0的默认规范限制，并非框架层面不支持，按以下步骤配置即可解决：

步骤1：为接口添加MIME类型匹配约束 #

给两个接口分别添加[Produces]特性，明确指定各自返回的MIME类型，让框架可以根据请求头自动匹配对应处理逻辑：

/// <summary>
/// 根据文件Id下载文件
/// </summary>
/// <response code="200">返回文件流用于下载</response>
/// <response code="404">文件Id不存在</response>
[HttpGet("files/{fileId}")]
[Produces(MediaTypeNames.Application.Octet)]
public async Task<IActionResult> GetFile([FromRoute] int fileId)
{
    var fileModel = await _boFileService.GetFileStreamAndFileName(fileId);
    return File(fileModel.Stream, MediaTypeNames.Application.Octet, fileModel.FileName);
}

/// <summary>
/// 根据文件Id获取文件详情
/// </summary>
/// <response code="200">返回文件的元数据信息，包括名称、状态、类型等</response>
/// <response code="404">文件Id不存在</response>
[HttpGet("files/{fileId}")]
[Produces(MediaTypeNames.Application.Json)]
public async Task<ActionResult<BoFileModel>> GetFileDetails([FromRoute] int fileId)
{
    return await _boFileService.GetFileDetails(fileId);
}

步骤2：启用内容协商配置 #

在项目的Program.cs（.NET 6+）或Startup.cs的控制器服务配置中，开启内容协商支持：

builder.Services.AddControllers(options =>
{
    // 启用Accept头匹配规则
    options.RespectBrowserAcceptHeader = true;
    // 当请求的Accept类型不支持时返回406错误，而非返回默认类型
    options.ReturnHttpNotAcceptable = true;
});

步骤3：修复Swagger报错 #

Swagger默认要求同HTTP方法+URL路径的组合唯一，因此需要自定义Swagger的生成规则，避免OperationId重复：

builder.Services.AddSwaggerGen(options =>
{
    // 自定义OperationId生成规则，将返回MIME类型纳入规则避免重复
    options.CustomOperationIds(apiDesc =>
    {
        var contentType = apiDesc.SupportedResponseTypes
            .SelectMany(r => r.ContentTypes)
            .Distinct()
            .FirstOrDefault() ?? "default";
        return $"{apiDesc.ActionDescriptor.RouteValues["action"]}_{contentType.Replace("/", "_")}";
    });
    
    // 如果你不需要在Swagger中展示其中一个接口，也可以给对应接口添加[ApiExplorerSettings(IgnoreApi = true)]特性直接隐藏，无需修改生成规则
});

配置完成后，请求时只要在请求头中指定对应的Accept值即可触发对应接口：

• 下载文件：设置请求头Accept: application/octet-stream
• 获取JSON格式详情：设置请求头Accept: application/json

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