快捷導(dǎo)航

SpringBoot使用Swagger生成多模塊的API文檔

更新時(shí)間：2025年02月14日 10:04:00 作者：五行星辰

這篇文章將以?Spring?Boot?多模塊項(xiàng)目為例,為大家詳細(xì)介紹一下如何使用?Swagger?生成多模塊的?API?文檔,感興趣的小伙伴可以了解一下

在大型項(xiàng)目中，通常會(huì)采用多模塊的架構(gòu)設(shè)計(jì)，以提高代碼的可維護(hù)性和可擴(kuò)展性。使用 Swagger 為多模塊項(xiàng)目生成 API 文檔時(shí)，需要進(jìn)行一些特殊的配置。以下以 Spring Boot 多模塊項(xiàng)目為例，詳細(xì)介紹如何使用 Swagger 生成多模塊的 API 文檔。

項(xiàng)目結(jié)構(gòu)

假設(shè)我們有一個(gè)包含多個(gè)模塊的 Spring Boot 項(xiàng)目，結(jié)構(gòu)如下：

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：添加依賴

在每個(gè)需要生成 API 文檔的模塊的 pom.xml 中添加 Swagger 相關(guān)依賴：

<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

在每個(gè)模塊中創(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 中也進(jìn)行類似的配置，只需將 basePackage 替換為 com.example.moduleb.controller。

步驟 3：統(tǒng)一 API 網(wǎng)關(guān)配置（可選）

如果項(xiàng)目中有 API 網(wǎng)關(guān)模塊（如 api-gateway），可以在該模塊中配置 Swagger，將各個(gè)模塊的 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 設(shè)置為包含所有模塊控制器的根包，這樣 Swagger 會(huì)掃描該包下所有模塊的控制器，并生成統(tǒng)一的 API 文檔。

步驟 4：添加 API 注解

在每個(gè)模塊的控制器類和方法上添加 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 的問候語(yǔ)", notes = "返回一個(gè)簡(jiǎn)單的問候語(yǔ)")
    public String hello() {
        return "Hello from Module A!";
    }
}

在 module-b 的控制器中也進(jìn)行類似的操作。

步驟 5：查看 API 文檔

啟動(dòng)各個(gè)模塊的 Spring Boot 應(yīng)用程序，訪問相應(yīng)模塊的 Swagger UI 地址（如 http://localhost:8080/module-a/swagger-ui.html 或 http://localhost:8080/api-gateway/swagger-ui.html，端口號(hào)和路徑根據(jù)實(shí)際情況修改），即可查看各個(gè)模塊或統(tǒng)一的 API 文檔。