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

在每個模塊中創(chuàng)建 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：統(tǒng)一 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 會掃描該包下所有模塊的控制器，并生成統(tǒng)一的 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，端口號和路徑根據實際情況修改），即可查看各個模塊或統(tǒng)一的 API 文檔。

注意事項

確保每個模塊的 Swagger 配置類中的 basePackage 配置正確，以確保能夠掃描到相應模塊的控制器。

如果使用 API 網關進行文檔聚合，要注意網關的路由配置，確保能夠正確訪問各個模塊的 API。

可以根據需要對 Swagger 的配置進行定制，如設置文檔標題、描述、版本等信息。

通過以上步驟，你可以為 Spring Boot 多模塊項目使用 Swagger 生成清晰、統(tǒng)一的 API 文檔，方便開發(fā)和測試人員查看和使用。

到此這篇關于SpringBoot使用Swagger生成多模塊的API文檔的文章就介紹到這了,更多相關SpringBoot Swagger生成API文檔內容請搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關文章希望大家以后多多支持腳本之家！

您可能感興趣的文章:

利用Java讀取Word表格中文本和圖片的方法實例
這篇文章主要給大家介紹了關于如何利用Java讀取Word表格中文本和圖片的相關資料,主要利用的是free spire.doc.jar 包,文中通過圖文介紹的非常詳細,需要的朋友可以參考下
2021-07-07
java+MongoDB實現(xiàn)存圖片、下載圖片的方法示例
這篇文章主要介紹了java+MongoDB實現(xiàn)存圖片、下載圖片的方法,結合實例形式詳細分析了java結合MongoDB實現(xiàn)圖片的存儲與下載相關操作技巧,需要的朋友可以參考下
2019-09-09
SpringBoot實現(xiàn)動態(tài)控制定時任務支持多參數功能
這篇文章主要介紹了SpringBoot實現(xiàn)動態(tài)控制定時任務-支持多參數功能，本文通過實例代碼給大家介紹的非常詳細，具有一定的參考借鑒價值,需要的朋友可以參考下
2019-05-05
利用MultipartFile實現(xiàn)文件上傳功能
這篇文章主要為大家詳細介紹了利用MultipartFile實現(xiàn)文件上傳功能，具有一定的參考價值，感興趣的小伙伴們可以參考一下
2017-11-11
Eclipse中如何顯示explorer過程解析
這篇文章主要介紹了Eclipse中如何顯示explorer過程解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下
2020-09-09
通過RedisTemplate連接多個Redis過程解析
這篇文章主要介紹了通過RedisTemplate連接多個Redis過程解析,文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值,需要的朋友可以參考下
2019-08-08
java finally塊執(zhí)行時機全面分析
下面小編就為大家?guī)硪黄猨ava finally塊執(zhí)行時機全面分析。小編覺得挺不錯的，現(xiàn)在就分享給大家，也給大家做個參考。一起跟隨小編過來看看吧
2016-08-08
Spring Cloud學習教程之DiscoveryClient的深入探究
這篇文章主要給大家介紹了關于Spring Cloud學習教程之DiscoveryClient的相關資料，文中通過示例代碼介紹的非常詳細，對大家的學習或者工作具有一定的參考學習價值，需要的朋友們下面隨著小編來一起學習學習吧。
2018-04-04
java8?時間日期的使用與格式化示例代碼詳解
這篇文章主要介紹了java8?時間日期的使用與格式化,本文通過示例代碼給大家介紹的非常詳細，對大家的學習或工作具有一定的參考借鑒價值，需要的朋友可以參考下
2022-06-06
SpringBoot監(jiān)控模塊Actuator的用法詳解
Spring?Boot?Actuator?是?Spring?Boot?自帶的一個功能模塊，提供了一組已經開箱即用的生產環(huán)境下常用的特性和服務，比如應用程序的健康檢查、信息暴露、度量收集、日志記錄等，本文將給大家詳細SpringBoot監(jiān)控模塊Actuator的用法
2023-06-06