当前位置：首页 > news >正文

Swagger2 Knife4jConfig 配置,父子项目swagger扫描多个子模块中的Controller生成接口文档:

news 来源：原创 2025/6/17 22:51:50

问题:

需求父子项目swagger扫描多个子模块中的Controller生成接口文档:

在这里插入图片描述

Swagger2Knife4jConfig 配置放在了 springboot-app 启动项目里，而 tiger-web 和 tiger-web2 这两个子项目有自己的 Controller。这种情况下，Swagger 可能无法正确扫描 tiger-web 和 tiger-web2 里的接口。你可以尝试以下几种方式来正确配置 Swagger（Knife4j）

确保 tiger-web 和 tiger-web2 里的 Controller 加上 @Api

例如：

package com.zz.web.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@Api(tags = "测试接口")
@RestController
@RequestMapping("/test")
public class TestController {

    @ApiOperation(value = "获取测试信息")
    @GetMapping("/info")
    public String getInfo() {
        return "Hello Swagger!";
    }
}
这样，Swagger 就能扫描到 tiger-web 和 tiger-web2 里的接口了。

方案 1：修改 Swagger2Knife4jConfig，支持多个模块

修改 Swagger2Knife4jConfig，扫描所有子模块 @ComponentScan(basePackages = {"com.zz.web", "com.zz.web2"}) // 扫描 web 和 web2 模块

你需要确保 Swagger2Knife4jConfig 能扫描 tiger-web 和 tiger-web2 里的 Controller。可以使用 @ComponentScan，或者修改 Docket 里的 basePackage。

package com.zz.app.config;

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.context.annotation.ComponentScan;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.Collections;

@Configuration
@EnableSwagger2WebMvc
@ComponentScan(basePackages = {"com.zz.web", "com.zz.web2"}) // 扫描 web 和 web2 模块
public class Swagger2Knife4jConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .protocols(Collections.singleton("https"))
                .host("https://www.tiger.com")
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) // 只扫描有 @Api 注解的 Controller
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("tiger-api文档")
                .description("springboot项目")
                .contact(new Contact("tiger", "https://tiger", "tiger@qq.com"))
                .termsOfServiceUrl("https://www.tiger.com/api")
                .version("1.0")
                .build();
    }
}

方案 2：在每个子模块 (tiger-web 和 tiger-web2) 里单独配置 Swagger

如果 tiger-web 和 tiger-web2 是独立的服务（分别启动），你可以在 tiger-web 和 tiger-web2 里分别配置 Swagger，而不是放到 springboot-app 里。
在 tiger-web 里新建 Swagger2Knife4jConfig.java

package com.zz.web.config;

import io.swagger.annotations.Api;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Swagger2Knife4jConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.zz.*.controller")) // 仅扫描 web 模块的 Controller
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("tiger-web API 文档")
                .description("tiger-web 模块接口文档")
                .contact(new Contact("tiger", "https://tiger", "tiger@qq.com"))
                .version("1.0")
                .build();
    }
}

然后，在 tiger-web2 里也创建一个类似的 Swagger2Knife4jConfig.java，修改 basePackage 为 com.zz.web2.controller。

方案 3：使用 @Import 让 springboot-app 统一加载多个模块的 Swagger 配置

你可以把 Swagger2Knife4jConfig 移动到 tiger-config 里，然后在 springboot-app 里用 @Import 引入。
在 tiger-config 里新建 Swagger2Knife4jConfig.java

package com.zz.config;

import io.swagger.annotations.Api;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

@Configuration
@EnableSwagger2WebMvc
public class Swagger2Knife4jConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) 
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("统一 API 文档")
                .description("springboot-app 统一 API")
                .contact(new Contact("tiger", "https://tiger", "tiger@qq.com"))
                .version("1.0")
                .build();
    }
}

在 springboot-app 里引入 Swagger2Knife4jConfig

package com.zz.app;

import com.zz.config.Swagger2Knife4jConfig;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Import;

@SpringBootApplication
@Import(Swagger2Knife4jConfig.class)
public class SpringbootAppApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootAppApplication.class, args);
    }
}

这样，springboot-app 启动后，Swagger 也能扫描 tiger-web 和 tiger-web2 里的 Controller 了。

结论

如果 tiger-web 和 tiger-web2 是独立的服务，建议方案 2，每个模块独立配置 Swagger。如果 springboot-app 统一启动所有模块，建议方案 1 或方案 3。

子模块过多可以设置分组

通过 groupName 在 Docket 配置中进行区分。因为你的 tiger-web 和 tiger-web2 都有 Controller，可以在 Swagger2Knife4jConfig 里为每个子项目单独创建 Docket，分别设置不同的 groupName。

package com.zz.app.swaggerConfig;

import io.swagger.annotations.Api;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2WebMvc;

import java.util.Collections;

/**
 * Knife4j配置类
 *
 * @author tiger
 */
@Configuration
@EnableSwagger2WebMvc
@ComponentScan(basePackages = {"com.zz.*"}) // 注意必须加: 扫描 web 和 web2 模块
public class Swagger2Knife4jConfig {

    @Bean
    public Docket webApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("tiger-web")  // 分组名称
                .protocols(Collections.singleton("https"))
                .host("https://www.tiger.com")
                .apiInfo(apiInfo("tiger-web API文档"))
                .select()
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.basePackage("com.zz.web.controller")) // 修改为实际的controller包路径
                .paths(PathSelectors.any())
                .build();
    }

    @Bean
    public Docket web2Api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("tiger-web2")  // 分组名称
                .protocols(Collections.singleton("https"))
                .host("https://www.tiger.com")
                .apiInfo(apiInfo("tiger-web2 API文档"))
                .select()
//                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .apis(RequestHandlerSelectors.basePackage("com.zz.web2.controller")) // 修改为实际的controller包路径
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(String title) {
        return new ApiInfoBuilder()
                .title(title)
                .description("springboot项目")
                .contact(new Contact("tiger", "https://tiger", "tiger@qq.com"))
                .termsOfServiceUrl("https://www.tiger.com/api")
                .version("1.0")
                .build();
    }
}