路由参数不同的多个HttpGet无法支持不同SwaggerResponse的问题

使用Swashbuckle.AspNetCore.Annotations为ASP.NET Core控制器生成API文档时，遇到以下问题：
控制器包含两个HttpGet端点：

• /entities：返回分页实体结果（PaginationResult<EntityTransferObject>）
• /entities/{id:guid}：返回单个实体结果（ExecuteQueryResult<EntityTransferObject>）

为两个端点配置不同的SwaggerResponse后，Swagger文档加载失败。但如果将两个端点的200响应类型改为相同，或仅为一个端点添加SwaggerResponse属性，文档就能正常生成。

已尝试的方法：

• 使用.NET Core原生的ProducesResponseType属性
• 将方法返回类型改为更具体的Task<ActionResult<T>>形式
  均未解决问题。

控制器代码如下：

[HttpGet]
[SwaggerOperation(
    Summary = "summary here",
    Description = "description",
    OperationId = "GetPage",
    Tags = new[] { "Entity" })]
[Produces("application/json")]
[SwaggerResponse(StatusCodes.Status200OK, type: typeof(PaginationResult<EntityTransferObject>))]
[SwaggerResponse(StatusCodes.Status401Unauthorized)]
[SwaggerResponse(StatusCodes.Status400BadRequest)]
public async Task<ActionResult> GetAsync(
    [FromQuery] [SwaggerParameter("The entity type", Required = true)] string entityType,
    [FromQuery] [SwaggerParameter("The page number to return", Required = true)]
    int page,
    [FromHeader(Name = "Authorization")] [SwaggerIgnore]
    string token)
{
}

[HttpGet("{id:guid}")]
[SwaggerOperation(
    Summary = "summary here",
    Description = "description",    
    OperationId = "GetEntity",
    Tags = new[] { "Entity" })]
[Produces("application/json")]
[SwaggerResponse(StatusCodes.Status200OK, type: typeof(ExecuteQueryResult<EntityTransferObject>))]
[SwaggerResponse(StatusCodes.Status401Unauthorized)]
[SwaggerResponse(StatusCodes.Status400BadRequest)]
public async Task<ActionResult> GetAsync(
    [FromRoute] [SwaggerParameter("The entity id", Required = true)] Guid id,
    [FromHeader(Name = "Authorization")] [SwaggerIgnore]
    string token)
{
}

以下是几种可行的解决思路，按优先级尝试：

1. 升级Swashbuckle.AspNetCore到最新稳定版 #

旧版本的Swashbuckle存在泛型类型处理、多端点响应类型解析的bug，升级到6.x及以上的最新稳定版，通常能解决这类兼容性问题。

2. 配置自定义SchemaId生成策略 #

Swashbuckle默认可能为泛型类型生成重复的SchemaId，导致文档冲突。在Program.cs（或Startup.cs）中添加自定义策略，确保每个泛型类型的ID唯一：

builder.Services.AddSwaggerGen(c =>
{
    c.CustomSchemaIds(type => 
    {
        if (type.IsGenericType)
        {
            return $"{type.Name.Split('`')[0]}_{string.Join("_", type.GetGenericArguments().Select(t => t.Name))}";
        }
        return type.Name;
    });
});

3. 结合ProducesResponseType与SwaggerResponse #

同时保留两种属性，明确指定响应描述，帮助Swashbuckle正确识别不同端点的响应类型：

// 分页端点
[ProducesResponseType(typeof(PaginationResult<EntityTransferObject>), StatusCodes.Status200OK)]
[SwaggerResponse(StatusCodes.Status200OK, "分页实体结果", typeof(PaginationResult<EntityTransferObject>))]

// 单个实体端点
[ProducesResponseType(typeof(ExecuteQueryResult<EntityTransferObject>), StatusCodes.Status200OK)]
[SwaggerResponse(StatusCodes.Status200OK, "单个实体结果", typeof(ExecuteQueryResult<EntityTransferObject>))]

4. 指定具体泛型返回类型 #

将方法返回类型从Task<ActionResult>改为具体的泛型形式，让Swashbuckle自动推断响应类型，同时保留SwaggerResponse补充文档：

// 分页端点
public async Task<ActionResult<PaginationResult<EntityTransferObject>>> GetAsync(...)

// 单个实体端点
public async Task<ActionResult<ExecuteQueryResult<EntityTransferObject>>> GetAsync(...)

5. 检查XML注释格式 #

如果启用了XML注释，确保两个方法的<returns>标签描述清晰，没有格式错误导致Swashbuckle解析失败。

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