SpringDoc OpenAPI中GroupedApi分组排序问题的分析与解决

问题背景

在SpringDoc OpenAPI项目中，开发人员在使用GroupedOpenApi进行API分组时遇到了一个排序问题。当创建多个API分组时，虽然可以通过displayName属性为每个分组设置友好的显示名称，但在最终生成的API文档列表（通过/v3/api-docs/swagger-config访问）中，分组的排序却是基于group名称而非displayName。

问题现象

通过一个典型示例可以清楚地看到这个问题：

@Bean
public GroupedOpenApi adminApi() {
    return GroupedOpenApi.builder()
        .displayName("yyyy - Admin Api")  // 显示名称以"y"开头
        .group("admin")                  // 组名以"a"开头
        .build();
}

@Bean
public GroupedOpenApi yellowApi() {
    return GroupedOpenApi.builder()
        .displayName("aaaa - Yellow Api") // 显示名称以"a"开头
        .group("yellow")                 // 组名以"y"开头
        .build();
}

按照预期，如果按照displayName排序，"aaaa - Yellow Api"应该排在"yyyy - Admin Api"前面。但实际结果却是按照group名称排序，导致"admin"组（a开头）排在"yellow"组（y开头）前面，与displayName的字母顺序相反。

技术分析

这个问题源于SwaggerUiConfigParameters类中的实现细节。在构建分组列表时，代码直接使用了group名称进行排序，而没有考虑displayName属性：

// 原始实现：按group名称排序
groups.sort(Comparator.comparing(Group::getName));

这种实现方式导致了显示顺序与开发人员预期的displayName顺序不一致。实际上，当引入了displayName属性后，排序逻辑应该相应更新以支持基于displayName的排序。

解决方案

正确的做法应该是修改排序逻辑，优先使用displayName进行排序。这可以通过以下方式实现：

// 修正后的实现：按displayName排序
groups.sort(Comparator.comparing(group -> 
    group.getDisplayName() != null ? group.getDisplayName() : group.getName()));

这种实现方式具有以下优点：

1. 首先尝试使用displayName进行排序
2. 如果displayName不存在，则回退到使用group名称
3. 保持了向后兼容性

实际影响

这个问题会直接影响Swagger UI中的API分组下拉菜单的显示顺序。虽然功能上不影响API的使用，但从用户体验角度来看：

1. 管理员无法通过displayName控制分组的显示顺序
2. 当displayName包含重要排序信息（如数字前缀或字母顺序）时，UI显示会显得混乱
3. 降低了API文档的可读性和易用性

最佳实践

在使用GroupedOpenApi时，建议：

1. 始终为分组设置有意义的displayName
2. 如果依赖特定排序，可以在displayName中加入数字前缀（如"01_GroupA"、"02_GroupB"）
3. 考虑displayName的字母顺序对最终排序的影响
4. 在需要精确控制排序时，可以自定义分组名称使其与displayName顺序一致

总结