SpringBoot整合Swagger3的分组问题及解决

Swagger3如果没有设置分组

你有没有遇到过这种情况：Swagger3刚搭好，一打开文档，所有接口都挤在一个叫“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", "http://www.baidu.com", "123456@qq.com"))
                .version("1.0版本")
                .build();
    }
}

总结

一句话：通过配置多个Docket并分别指定groupName，就能轻松实现API分组管理，让接口文档告别混乱，井井有条。实际项目中，你还可以按业务模块继续扩展分组，甚至结合动态配置来适应多环境需求。直接上手试试吧，效果立竿见影。