knife4j 中接口分组排序的方法

使用的依赖版本

implementation 'com.github.xiaoymin:knife4j-openapi3-jakarta-spring-boot-starter:4.5.0'	

即 knife4j + springdoc

原理解析

knife4j界面左上角的下拉框里的每一项对应一个 GroupedOpenApi Bean，浏览器F12里的 /v3/api-docs/swagger-config请求结果中，urls字段就对应每一个 GroupedOpenApi 。/v3/api-docs/名字即对应该 GroupedOpenApi中的接口分组查询请求

接口分组查询结果中的tags字段就是用来实现排序的字段，只有当Controller上的@Tag注解同时填写name和description字段时，这个分组才会进入到tags字段中

在此基础上，如果没有特殊处理，tags字段的原始顺序就是分组的显示顺序，处理方法则有3种：

官方方法（实测无效）

来自官方文档

在接口上添加注解来为tags中的对象添加x-order字段

但是当前版本实测无效，该字段并没出现

插件方法

来自Gitee issues

在@Tag注解上添加插件手动添加x-order字段

@Tag(name = "A", description = "A", extensions = {
        @Extension(properties = {@ExtensionProperty(name = "x-order", value = "100", parseValue = true)}
        )
})

实测有效，每个Controller单独指定更灵活，但是增加代码量略大

Customiser方法(推荐)

来自CSDN

在GroupedOpenApi.builder()后调用方法addOpenApiCustomiser增加一步处理，手动对tags字段进行排序

这里选择按照description字段来排序，反正它也不显示在界面上

fun buildGroupedOpenApi(pathPrefix: String, groupName: String): GroupedOpenApi {
    logger.info("[Docket] 创建API文档: group: $groupName prefix:$pathPrefix")
    return GroupedOpenApi.builder().group(groupName).pathsToMatch("${pathPrefix}/**")
        .addOpenApiCustomizer { api ->
            api.tags = api.tags?.sortedWith(Comparator.comparing { tag -> StringUtils.stripAccents(tag.description) })
        }
        .build()
}

这样把description字段当做order字段来使用即可

实测有效，灵活性与插件方法相当，代码量只是在工具方法上加了一句而已