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

问题:

需求父子项目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,支持多个模块

  1. 修改 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();
    }
}
相关推荐
视睿39 分钟前
【C++练习】06.输出100以内的所有素数
开发语言·c++·算法·机器人·无人机
草莓熊Lotso1 小时前
从 “Hello AI” 到企业级应用:Spring AI 如何重塑 Java 生态的 AI 开发
java·人工智能·经验分享·后端·spring
doulbQuestion1 小时前
【无标题】
java·spring
Metaphor6921 小时前
Java 旋转 PDF 页面:使用 Spire.PDF 实现高效页面处理
java·经验分享·pdf
Terio_my1 小时前
Spring Boot 整合 Elasticsearch
spring boot·后端·elasticsearch
jjjxxxhhh1231 小时前
【QT】-QT为啥喜欢用类而不是结构体
开发语言·qt
哈利路亚胡辣汤2 小时前
spring多数据源配置
java·spring·mybatis
卷Java2 小时前
智慧停车大屏数据分析与设计文档
java·大数据·人工智能·数据分析
zzzsde2 小时前
【c++】深入理解string类(3):典型OJ题
开发语言·c++
雨落在了我的手上2 小时前
C语言趣味小游戏----猜数字小游戏
c语言·开发语言·游戏