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 網(wǎng)關配置（可選）

如果項目中有 API 網(wǎng)關模塊（如 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，端口號和路徑根據(jù)實際情況修改），即可查看各個模塊或統(tǒng)一的 API 文檔。