Swashbuckle.AspNetCore 控制器排序问题解决方案

问题背景

在使用 Swashbuckle.AspNetCore 为 ASP.NET Core 应用生成 API 文档时，开发者经常会遇到控制器排序不符合预期的问题。特别是在多项目结构中，当控制器分布在不同的程序集（如共享库和主应用）时，默认的排序行为可能无法满足需求。

典型场景

假设我们有以下控制器结构：

1. 共享库中的 PingController（Xxx.Yyy.Common.Controllers.Ping.PingController）
2. 主应用中的 HealthChecksController 和 SamplesController

期望的排序顺序是：

• HealthChecks
• Ping
• Samples

常见误区

许多开发者会尝试使用 OrderActionsBy 方法来控制排序：

options.OrderActionsBy(
    apiDesc => 
        $"{apiDesc.ActionDescriptor.RouteValues["controller"]}_{apiDesc.RelativePath}_{apiDesc.HttpMethod}"
);

这种方法虽然能对控制器内部的端点方法进行排序，但对控制器本身的排序无效。这是因为 OrderActionsBy 主要影响的是同一控制器下各个操作的排序，而非控制器级别的排序。

解决方案

方案一：使用 DocumentFilter（不推荐）

可以通过实现 IDocumentFilter 接口来手动指定标签顺序：

public class ApiControllerTagDescriptions : IDocumentFilter
{
    public void Apply(OpenApiDocument swaggerDoc, DocumentFilterContext context)
    {
        swaggerDoc.Tags = new List<OpenApiTag>
        {
            new OpenApiTag{ Name = "HealthChecks", Description = "HealthChecks" },
            new OpenApiTag{ Name = "Ping", Description = "Ping" },
            new OpenApiTag{ Name = "Samples", Description = "Samples" }
        };
    }
}

然后在配置中注册：

options.DocumentFilter<ApiControllerTagDescriptions>();

缺点：这种方法需要硬编码控制器名称，维护成本高，特别是在多项目或频繁变更的场景下。

方案二：配置 SwaggerUI 排序选项（推荐）

更优雅的解决方案是直接配置 SwaggerUI 的排序行为：

services.Configure<SwaggerUIOptions>(options =>
{
    // 控制器或标签级别的排序（UI中的顶层分组）
    options.ConfigObject.AdditionalItems["tagsSorter"] = "alpha";
    
    // 控制器内部操作的排序（端点方法）
    options.ConfigObject.AdditionalItems["operationsSorter"] = "alpha";
});

参数说明：

• "alpha"：按字母顺序排序（适用于路径或标签）
• "method"：按HTTP方法排序（仅适用于操作）
• 默认/省略：使用规范文档中的原始顺序

技术原理

这种解决方案之所以有效，是因为它直接配置了 SwaggerUI 的客户端排序行为。SwaggerUI 提供了内置的排序器：

1. tagsSorter：控制顶层标签/控制器的排序
2. operationsSorter：控制每个控制器内部操作的排序

通过设置这些参数，我们可以覆盖默认的排序行为，而无需修改生成的 OpenAPI 规范文档本身。

最佳实践

1. 对于简单的字母排序需求，使用 "alpha" 即可满足大多数场景
2. 如果需要更复杂的排序逻辑，可以编写自定义的 JavaScript 排序函数
3. 在多项目环境中，这种配置方式比硬编码控制器名称更易于维护
4. 建议将 Swagger 配置集中管理，便于统一维护和更新

注意事项

1. 此解决方案主要影响 SwaggerUI 的展示顺序，不会改变生成的 OpenAPI 规范文档
2. 如果 API 文档会被其他工具使用，需要考虑那些工具可能使用不同的排序逻辑
3. 在 .NET 8 环境中验证通过，但原理适用于其他版本的 ASP.NET Core

通过这种配置方式，开发者可以轻松实现控制器的预期排序，同时保持代码的简洁性和可维护性。