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

发布于：2025-04-01 ⋅ 阅读:(25) ⋅ 点赞:(0)

在现代企业级应用开发中，前后端分离已成为主流模式，前端负责界面呈现，后端专注提供 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 {

    @Bean
    public 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 {

    @Autowired
    private MockMvc mockMvc;

    @Test
    public 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 文档，极大提升开发效率和团队协作能力。本文从基础集成到单元测试，再到进阶配置，涵盖了完整实践过程，希望对你有所帮助。

网站公告

今日签到

点亮在社区的每一天
去签到

热门文章

最新发布