Spring Boot 3.4.3 基于 SpringDoc 2 和 Swagger 3 实现项目接口文档管理

在现代企业级应用开发中，前后端分离已成为主流模式，前端负责界面呈现，后端专注提供 RESTful API 接口。然而，接口文档的编写和维护往往是开发过程中的痛点。Spring Boot 3.4.3 结合 SpringDoc 2 和 Swagger 3，为开发者提供了一种高效的方式，通过 OpenAPI 3 标准自动生成和管理接口文档。本文将详细介绍如何在 Spring Boot 3.4.3 中集成 SpringDoc 2 和 Swagger 3，构建标准化的接口文档，并附上完整的代码示例和单元测试指南。

---

1. SpringDoc 和 Swagger 简介

1.1 什么是 SpringDoc？

SpringDoc 是一个开源库，专为 Spring 框架设计，用于根据项目代码自动生成符合 OpenAPI 3.0 规范的 API 文档。它通过扫描控制器和注解，生成详细的接口信息，帮助开发者轻松创建和维护 RESTful API 文档。

1.2 Swagger 的作用

Swagger 是一个广受欢迎的 API 文档工具，Swagger 3 基于 OpenAPI 3.0 标准，提供可视化的接口文档界面（Swagger UI），支持在线查看和测试 API。SpringDoc 将 Swagger 的功能集成到 Spring 项目中，简化了配置流程。

1.3 优点

• 自动化：无需手动编写文档，减少维护成本。
• 标准化：遵循 OpenAPI 3.0，提供一致的文档格式。
• 交互性：Swagger UI 支持在线调试 API，提升开发效率。

---

2. 使用场景

SpringDoc 和 Swagger 适用于以下场景：

• 前后端分离：为前端提供清晰的接口说明。
• 团队协作：确保开发者和测试人员快速理解 API。
• 微服务架构：管理多个服务的接口文档。
• 快速迭代：接口变更时自动更新文档。

---

3. 项目实战

以下是基于 Spring Boot 3.4.3 集成 SpringDoc 2 和 Swagger 3 的完整步骤。

3.1 添加 Maven 依赖

在 pom.xml 中添加必要的依赖：

<dependencies><!-- Spring Boot Web --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><!-- SpringDoc OpenAPI --><dependency><groupId>org.springdoc</groupId><artifactId>springdoc-openapi-starter-webmvc-ui</artifactId><version>2.0.2</version></dependency><!-- 测试支持 --><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
</dependencies>

说明：

• springdoc-openapi-starter-webmvc-ui 集成了 Swagger UI 和 OpenAPI 3 支持。
• Spring Boot 3.4.3 默认使用 Jakarta EE，无需额外处理兼容性问题。

3.2 创建 RESTful 接口

创建一个简单的控制器示例：

package cn.joyous.controller;import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;@RestController
@RequestMapping("/api")
@Tag(name = "用户管理", description = "用户相关操作接口")
public class UserController {@Operation(summary = "获取用户信息", description = "根据用户ID获取详细信息")@GetMapping("/user/{id}")public String getUser(@PathVariable("id") Long id) {return "User ID: " + id;}@Operation(summary = "创建用户", description = "新增一个用户")@PostMapping("/user")public String createUser(@RequestParam("name") String name) {return "User created: " + name;}
}

注解说明：

• @Tag：定义接口分组。
• @Operation：描述接口的功能和详情。
• SpringDoc 会根据这些注解生成文档。

3.3 配置 SpringDoc（可选）

SpringDoc 默认无需额外配置即可使用 Swagger UI。如果需要自定义文档信息，可以添加配置类：

package cn.joyous.config;import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Info;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;@Configuration
public class SpringDocConfig {@Beanpublic OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("Spring Boot 3.4.3 API 文档").version("1.0.0").description("基于 SpringDoc 2 和 Swagger 3 的接口文档示例"));}
}

3.4 启动与访问

1. 启动 Spring Boot 应用（默认端口 8080）。
2. 访问 Swagger UI：http://localhost:8080/swagger-ui/index.html。
3. 你将看到自动生成的接口文档，包括 /api/user/{id} 和 /api/user 两个接口，支持在线测试。

---

4. 单元测试

为确保接口文档和功能正常运行，可以编写单元测试。

4.1 测试依赖

确保 pom.xml 已包含 spring-boot-starter-test。

4.2 测试代码

创建一个测试类：

package cn.joyous.controller;import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;@SpringBootTest
@AutoConfigureMockMvc
public class UserControllerTest {@Autowiredprivate MockMvc mockMvc;@Testpublic void testGetUser() throws Exception {mockMvc.perform(get("/api/user/1")).andExpect(status().isOk()).andExpect(content().string("User ID: 1"));}
}

说明：

• @SpringBootTest：加载 Spring 上下文。
• @AutoConfigureMockMvc：启用 MockMvc 用于模拟 HTTP 请求。
• 测试验证了 /api/user/{id} 接口的正确性。

4.3 运行测试

在 IDE 中运行测试，确保接口返回预期结果。

---

5. 进阶配置（可选）

1. 多环境支持
   在 SpringDocConfig 中配置不同环境的服务器地址：

   import io.swagger.v3.oas.models.servers.Server;@Bean
   public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档").version("1.0.0")).addServersItem(new Server().url("http://localhost:8080").description("开发环境")).addServersItem(new Server().url("https://api.example.com").description("生产环境"));
   }
   

2. 分组接口
   使用 @Tag 或 SpringDoc 的分组功能分隔不同模块的接口：

   @Bean
   public GroupedOpenApi userApi() {return GroupedOpenApi.builder().group("user-api").pathsToMatch("/api/user/**").build();
   }
   

3. 安全性集成
   若项目使用 Spring Security，可添加认证支持：

   @Bean
   public OpenAPI customOpenAPI() {return new OpenAPI().info(new Info().title("API 文档")).addSecurityItem(new SecurityRequirement().addList("bearerAuth")).components(new Components().addSecuritySchemes("bearerAuth",new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")));
   }
   

---

6. 总结

Spring Boot 3.4.3 结合 SpringDoc 2 和 Swagger 3，为接口文档管理提供了一套高效、标准化的解决方案。通过简单的依赖引入和少量配置，你可以快速生成交互式的 API 文档，极大提升开发效率和团队协作能力。本文从基础集成到单元测试，再到进阶配置，涵盖了完整实践过程，希望对你有所帮助。