Knife4j 4.5.0 如何配置接口文档排序？

Question

在使用 Knife4j 4.5.0 构建 Spring Boot 项目时，如何通过 `@ApiSort` 注解或配置类对多个 Controller 的接口文档进行排序显示？当前版本中默认按字母顺序排列，但业务需要按模块重要性自定义排序，应如何正确配置 `OpenApi` Bean 或启用增强模式以支持界面排序展示？

Answer 1

1. 背景与问题引入

在使用 Knife4j 4.5.0 构建 Spring Boot 项目时，API 文档的可读性与组织结构对前后端协作至关重要。默认情况下，Swagger 和 Knife4j 按 Controller 类名的字母顺序展示接口模块，这在中大型项目中往往无法满足业务模块优先级排序的需求。

例如，订单模块（OrderController）比工具类模块（UtilController）更重要，应优先展示。因此，如何通过 @ApiSort 注解或 OpenAPI 配置实现自定义排序，成为提升文档体验的关键问题。

2. 核心机制解析：@ApiSort 与增强模式

@ApiSort 是 Knife4j 提供的注解，用于控制 Controller 在 UI 界面中的显示顺序。其底层依赖于 Knife4j 的“增强模式”（enableSwaggerBootstrap），该模式扩展了原生 Swagger 功能，支持更多可视化定制。

启用增强模式后，Knife4j 会读取 @ApiSort 中的数值进行升序排列（值越小越靠前）。若未启用增强模式，则此注解无效。

注解/配置项	作用范围	是否必需	默认值
@ApiSort	Controller 类上	否（按需使用）	Integer.MAX_VALUE
enableSwaggerBootstrap	knife4j 配置项	是（启用排序前提）	false
OpenApi customizer	编程式排序	可选	无

3. 实践步骤一：启用 Knife4j 增强模式

必须在 application.yml 中开启增强模式，否则 @ApiSort 不生效：

knife4j:
  enable-swagger-bootstrap: true
  production: false
  basic:
    enable: false

该配置告知 Knife4j 启动增强功能，包括排序、搜索、动态参数等高级特性。

4. 实践步骤二：使用 @ApiSort 注解控制顺序

在各个 Controller 上添加 @ApiSort 注解，指定排序权重：

@RestController
@RequestMapping("/api/order")
@ApiSort(1)
@Tag(name = "订单管理模块")
public class OrderController {
    // 接口方法...
}

@RestController
@RequestMapping("/api/user")
@ApiSort(2)
@Tag(name = "用户管理模块")
public class UserController {
    // 接口方法...
}

@RestController
@RequestMapping("/api/report")
@ApiSort(100)
@Tag(name = "报表工具模块")
public class ReportController {
    // 接口方法...
}

上述代码中，OrderController 将排在最前，ReportController 最后，实现按业务重要性排序。

5. 替代方案：通过 OpenApi Bean 编程式排序

对于更复杂的排序逻辑（如根据包路径、注解元数据动态排序），可通过自定义 OpenApiCustomizer 实现：

@Bean
public OpenApiCustomizer sortApisByController() {
    return openApi -> {
        openApi.getTags().sort(Comparator.comparing(tag -> {
            try {
                Class<?> clazz = Class.forName("com.example.controller." + tag.getName().replaceAll("模块", "") + "Controller");
                ApiSort apiSort = clazz.getAnnotation(ApiSort.class);
                return apiSort != null ? apiSort.value() : Integer.MAX_VALUE;
            } catch (ClassNotFoundException e) {
                return Integer.MAX_VALUE;
            }
        }));
    };
}

该方式适用于无法直接修改 Controller 的场景，或需结合反射动态计算排序值。

6. 排错与常见问题分析

• @ApiSort 无效？ 检查是否启用 enable-swagger-bootstrap: true
• 排序混乱？ 确保所有 Controller 都显式设置 @ApiSort，避免默认值干扰
• 标签重复？ 使用 @Tag 明确命名，避免 Swagger 自动推断导致冲突
• 生产环境不显示？ 检查 knife4j.production 是否设为 false

graph TD A[开始] --> B{是否启用增强模式?} B -- 否 --> C[启用 enable-swagger-bootstrap: true] B -- 是 --> D[在Controller添加@ApiSort] D --> E[启动应用] E --> F{排序是否生效?} F -- 否 --> G[检查OpenApi Customizer或注解位置] F -- 是 --> H[完成]

7. 高级技巧：结合包扫描与自动化排序

可编写工具类，在项目启动时扫描指定包下的 Controller，根据包层级自动分配排序权重：

public int calculateSortWeight(String packageName) {
    if (packageName.contains("core")) return 10;
    if (packageName.contains("biz")) return 20;
    if (packageName.contains("util")) return 99;
    return 50;
}

再结合 Spring 的 ApplicationContext 扫描所有 Controller Bean，动态注册排序规则，实现零侵入式管理。

8. 性能与维护建议

虽然 @ApiSort 对性能无显著影响，但在超大规模 API 场景下（>500 接口），建议：

• 统一定义排序常量类（如 ApiSortConstants.ORDER = 1）
• 避免频繁变更排序值，防止团队成员文档认知偏差
• 结合 CI/CD 输出 API 文档快照，便于版本追溯
• 使用 Knife4j 的 Markdown 导出功能生成离线文档