SpringBoot使用Swagger生成多模块的API文档

更新时间：2025年02月14日 10:04:00 作者：五行星辰

这篇文章将以 Spring Boot 多模块项目为例,为大家详细介绍一下如何使用 Swagger 生成多模块的 API 文档,感兴趣的小伙伴可以了解一下

在大型项目中，通常会采用多模块的架构设计，以提高代码的可维护性和可扩展性。使用 Swagger 为多模块项目生成 API 文档时，需要进行一些特殊的配置。以下以 Spring Boot 多模块项目为例，详细介绍如何使用 Swagger 生成多模块的 API 文档。

项目结构

假设我们有一个包含多个模块的 Spring Boot 项目，结构如下：

multi-module-project
├── common-module
│ └── src
│ └── main
│ └── java
│ └── com
│ └── example
│ └── common
│ └── ...
├── module-a
│ └── src
│ └── main
│ └── java
│ └── com
│ └── example
│ └── modulea
│ └── ...
├── module-b
│ └── src
│ └── main
│ └── java
│ └── com
│ └── example
│ └── moduleb
│ └── ...
└── api-gateway
└── src
└── main
└── java
└── com
└── example
└── apigateway
└── ...

步骤 1：添加依赖

在每个需要生成 API 文档的模块的 pom.xml 中添加 Swagger 相关依赖：

<dependencies>
    <!-- Swagger API 注解 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>2.9.2</version>
    </dependency>
    <!-- Swagger UI -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>2.9.2</version>
    </dependency>
</dependencies>

步骤 2：配置 Swagger

在每个模块中创建 Swagger 配置类，例如在 module-a 中：

package com.example.modulea.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example.modulea.controller"))
               .paths(PathSelectors.any())
               .build();
    }
}

在 module-b 中也进行类似的配置，只需将 basePackage 替换为 com.example.moduleb.controller。

步骤 3：统一 API 网关配置（可选）

如果项目中有 API 网关模块（如 api-gateway），可以在该模块中配置 Swagger，将各个模块的 API 文档聚合在一起。

package com.example.apigateway.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
 
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.basePackage("com.example"))
               .paths(PathSelectors.any())
               .build();
    }
}

这里的 basePackage 设置为包含所有模块控制器的根包，这样 Swagger 会扫描该包下所有模块的控制器，并生成统一的 API 文档。

步骤 4：添加 API 注解

在每个模块的控制器类和方法上添加 Swagger 注解，以描述 API 信息。例如在 module-a 的控制器中：

package com.example.modulea.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;
 
@RestController
@RequestMapping("/module-a")
@Api(value = "Module A API", description = "这是 Module A 的 API 文档")
public class ModuleAController {
    @GetMapping("/hello")
    @ApiOperation(value = "获取 Module A 的问候语", notes = "返回一个简单的问候语")
    public String hello() {
        return "Hello from Module A!";
    }
}

在 module-b 的控制器中也进行类似的操作。

步骤 5：查看 API 文档

启动各个模块的 Spring Boot 应用程序，访问相应模块的 Swagger UI 地址（如 http://localhost:8080/module-a/swagger-ui.html 或 http://localhost:8080/api-gateway/swagger-ui.html，端口号和路径根据实际情况修改），即可查看各个模块或统一的 API 文档。

注意事项

确保每个模块的 Swagger 配置类中的 basePackage 配置正确，以确保能够扫描到相应模块的控制器。

如果使用 API 网关进行文档聚合，要注意网关的路由配置，确保能够正确访问各个模块的 API。

可以根据需要对 Swagger 的配置进行定制，如设置文档标题、描述、版本等信息。

通过以上步骤，你可以为 Spring Boot 多模块项目使用 Swagger 生成清晰、统一的 API 文档，方便开发和测试人员查看和使用。

到此这篇关于SpringBoot使用Swagger生成多模块的API文档的文章就介绍到这了,更多相关SpringBoot Swagger生成API文档内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

springboot+camunda实现工作流的流程分析
Camunda是基于Java语言，支持BPMN标准的工作流和流程自动化框架，并且还支持CMMN规范，DMN规范，本文给大家介绍springboot+camunda实现工作流的流程分析，感兴趣的朋友一起看看吧
2021-12-12
浅谈spring boot 1.5.4 异常控制
下面小编就为大家带来一篇浅谈spring boot 1.5.4 异常控制。小编觉得挺不错的，现在就分享给大家，也给大家做个参考。一起跟随小编过来看看吧
2017-06-06
查询Java程序日志的实现方式
在Linux中查询Java日志需定位路径（如/var/log/、/opt/、~/, 使用find）、用tail/grep查看内容、journalctl查系统服务日志、调整日志级别、监控变化及管理日志轮转
2025-09-09
Java Web开发之基于Session的购物商店实现方法
这篇文章主要介绍了Java Web开发之基于Session的购物商店实现方法,涉及Java针对session的操作及数据库操作技巧,具有一定参考借鉴价值,需要的朋友可以参考下
2015-10-10
idea远程调试spark的步骤讲解
今天小编就为大家分享一篇关于idea远程调试spark的步骤讲解，小编觉得内容挺不错的，现在分享给大家，具有很好的参考价值，需要的朋友一起跟随小编来看看吧
2019-03-03
Spring自动注入失败的解决方法
这篇文章主要介绍了Spring自动注入失败的解决方法，帮助大家更好的理解和学习使用Spring框架，感兴趣的朋友可以了解下
2021-05-05
java代理模式（jdk proxy）
代理(Proxy)是一种设计模式,提供了对目标对象另外的访问方式;这篇文章主要介绍了Java 中的三种代理模式,需要的朋友可以参考下，希望能帮助到你
2021-07-07
Maven Pom 文件中的隐式依赖导致Jar冲突问题
这篇文章主要介绍了Maven Pom 文件中的隐式依赖导致Jar冲突问题，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-12-12
Java使用XML与注解方式实现CRUD操作代码
MyBatis提供了灵活的配置和使用方式,使得数据库操作更加简洁和高效,通过本文,我们介绍了如何使用MyBatis框架,通过XML映射文件和注解两种方式来实现数据库的增删改查操作,感兴趣的朋友跟随小编一起看看吧
2024-02-02
Spring Boot 3.x开发中MySQL 8.x窗口函数在JPA中的使用限制问题详解
开窗函数是在MySQL8.0以后才新加的功能,因此要想直接使用开窗函数,则mysql版本要8.0以上,这篇文章主要介绍了Spring Boot 3.x开发中MySQL 8.x窗口函数在JPA中的使用限制问题的相关资料,需要的朋友可以参考下
2026-04-04