Swagger3未设置分组时接口文档混乱怎么办？

你是否遇到过这样的问题：刚刚搭建好Swagger3，打开API文档时，发现所有接口都堆集在名为“default”的默认分组中，路径和描述密密麻麻，让人眼花缭乱？

效果如下图所示：

随着项目功能模块和接口数量持续增长

混乱程度也会急剧增加。若想查找特定模块的接口，不得不从数百个端点中逐一筛选，开发效率显著降低。那么，如何解决？核心方案就是——为API接口进行分组管理。

Swagger3的分组功能非常灵活：只需配置多个Docket实例，并通过groupName()方法为每个实例设置独立的组名称。这样，接口文档便能按照模块规范有序地归类展示。

以下是一个典型的分组配置示例，分别创建“User”和“Sys”两个分组，各自扫描对应的控制器包路径：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger3Config {

    @Bean
    public Docket createRestApi1() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("User")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bc.work.controller.user"))
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket createRestApi2() {
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .groupName("Sys")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bc.work.controller.sys"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger3接口文档")
                .description("接口文档描述部分")
                .contact(new Contact("bc", "https://www.baidu.com", "123456@qq.com"))
                .version("1.0版本")
                .build();
    }
}

总结：分组配置让接口文档井然有序

总而言之，通过配置多个Docket实例并分别为其指定groupName，即可轻松实现API分组管理，彻底告别接口文档的混乱局面，变得井井有条。在实际项目开发中，你还可以根据业务模块进一步扩展分组，甚至结合动态配置策略来适配不同环境的需求。快动手实践一下吧，效果立竿见影。