OpenAPI 3单YAML文件如何按URI拆分Swagger UI接口分组

完全可以实现，效果和你之前用Springfox配置出来的分组下拉选择完全一致，也不会占用你已经用于接口内部分类的tags字段，完全适配你当前用OpenAPI 3 YAML编写规范、gradle-swagger-generator-plugin生成文档的场景。

实现逻辑和Springfox的思路本质相同：按URI规则把接口拆成多份独立的OpenAPI描述文件，再让Swagger UI加载多份描述文件，自动渲染顶部的分组下拉菜单。你不需要手动维护多份YAML文件，所用的gradle-swagger-generator-plugin本身就原生支持这个能力，配置步骤如下：

配置步骤 #

直接在项目的build.gradle中添加对应配置即可：

// 指向你日常维护的单份OpenAPI YAML主文件
resolveOpenAPI {
    inputFile = file("src/main/resources/openapi.yaml")
}

generateSwaggerUI {
    // 配置按路径规则自动拆分独立的接口描述文件
    specMerging {
        // 第一个分组：匹配所有/api/v1/something前缀的接口
        create("SomeGroup") {
            outputFile = file("${buildDir}/swagger/some-group.json")
            pathFilter = { it.startsWith("/api/v1/something") }
        }
        // 第二个分组：匹配/api/v1/前缀下、不属于上面分组的其余接口
        create("SomeOtherGroup") {
            outputFile = file("${buildDir}/swagger/some-other-group.json")
            pathFilter = { it.startsWith("/api/v1/") && !it.startsWith("/api/v1/something") }
        }
    }

    // 配置Swagger UI的下拉分组列表
    swaggerUI {
        urls = [
            [name: "SomeGroup", url: "some-group.json"],
            [name: "SomeOtherGroup", url: "some-other-group.json"]
        ]
        // 可选：指定页面默认加载展示的分组
        urlsPrimaryName = "SomeOtherGroup"
    }
}

注意点 #

• 你全程只需要维护一份完整的OpenAPI YAML文件即可，构建阶段插件会自动按配置的路径规则拆出两份独立的接口描述，公共的schema、参数、响应定义不需要重复编写
• 现有tags配置不需要做任何改动，标签只在单个分组内部承担接口分类的作用，和顶层的spec分组逻辑完全不冲突
• 构建完成后生成的Swagger UI页面，顶部会出现和你之前用Springfox实现效果完全一致的分组下拉选择器，切换时仅展示对应分组下的接口，和你给出的示例效果没有区别

如果你不想用插件的自动拆分能力，也可以手动维护两份独立的OpenAPI YAML文件，直接把两个文件的访问地址配置到swaggerUI.urls参数里，最终展示效果是一样的，只是手动维护多份文件很容易出现公共定义不同步的问题，更推荐用插件自动拆分的方案。

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