SpringBoot整合SpringDoc

一、SpringDoc 是什么？

SpringDoc 是一个基于 OpenAPI 3.0 规范的开源 API 文档生成工具，专为 Spring Boot 应用设计。它能自动扫描项目中的 REST 接口，生成标准化的 API 文档，并提供交互式 UI（默认集成 Swagger UI），支持在线调试接口。

简单说：SpringDoc = 自动 API 文档生成器 + 可视化调试工具，核心依赖 OpenAPI 3.0 规范（Swagger2 基于旧版 OpenAPI 2.0）。

二、为什么选择 SpringDoc？

相比传统的 Swagger2 或手写文档，SpringDoc 的核心优势：

兼容性更好原生支持 Spring Boot 2.x/3.x，尤其是对 Spring Boot 3.x 的适配远优于 Swagger2（Swagger2 对 3.x 支持有限）。
配置极简开箱即用，无需大量模板代码，仅需添加依赖即可生成基础文档，通过少量注解或配置即可完善文档。
基于 OpenAPI 3.0支持更多新特性：如请求体示例、OAuth2 认证、接口版本控制等，更符合现代 API 设计规范。
与 Spring 生态深度融合自动识别 Spring 原生注解（@GetMapping、@RequestBody等），无需重复标注，减少代码冗余。
多 UI 支持默认集成 Swagger UI，还可扩展支持 OpenAPI UI、ReDoc 等，满足不同团队的使用习惯。

三、环境准备

JDK：1.8 及以上（Spring Boot 3.x 需 JDK 17+）
Spring Boot 版本：2.7.x（本文以此为例，3.x 配置类似，差异见后文说明）
依赖管理：Maven 或 Gradle
开发工具：IDEA（推荐，支持注解提示）

四实现过程

步骤 1：创建 Spring Boot 项目

通过Spring Initializr或者Maven快速创建项目，名为SpringDoc-Demo：

选择 Spring Web 依赖（用于开发 REST 接口）。
填写项目信息（Group、Artifact 等），生成项目后导入 IDEA。

步骤 2：添加 SpringDoc 依赖

SpringDoc 的核心依赖是springdoc-openapi-ui，它包含 OpenAPI 3.0 实现和 Swagger UI 界面。

修改Maven 项目（pom.xml）

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <!-- SpringBoot父依赖 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.7.4</version>
        <relativePath/>
    </parent>

    <groupId>com.yqd</groupId>
    <artifactId>SpringBoot-Swagger-Demo</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <name>SpringBoot-Swagger-Demo</name>
    <url>http://maven.apache.org</url>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- SpringBoot 核心依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- SpringDoc 核心依赖（包含OpenAPI 3.0和Swagger UI） -->
        <dependency>
            <groupId>org.springdoc</groupId>
            <artifactId>springdoc-openapi-ui</artifactId>
            <version>1.6.15</version> <!-- 适配Spring Boot 2.7.x的稳定版本 -->
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.24</version>
            <optional>true</optional>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

版本说明：

Spring Boot 2.7.x → 使用 1.6.x 版本（如 1.6.15）。

Spring Boot 3.x → 需使用2.x版本（如 2.1.0），且依赖坐标改为：org.springdoc:springdoc-openapi-starter-webmvc-ui:2.1.0

步骤 3：基础配置（自定义文档信息）

SpringDoc 默认会扫描所有@RestController接口并生成基础文档。若需自定义文档标题、版本等信息，可通过配置文件或 Java 代码实现。

方式 1：通过 application.yml 配置（推荐）

在src/main/resources/application.yml中添加：

springdoc:
  api-docs:
    path: /api-docs  # OpenAPI文档的JSON接口路径（默认/ v3/api-docs）
  swagger-ui:
    path: /swagger-ui.html  # Swagger UI界面路径（默认/swagger-ui.html）
    operationsSorter: method  # 接口排序方式（method按方法名，alpha按路径）
  packages-to-scan: com.yqd.controller  # 指定扫描的Controller包（可选）

# 自定义OpenAPI文档信息
openapi:
  info:
    title: "用户管理系统API"  # 文档标题
    description: "基于SpringDoc的API文档示例"  # 文档描述
    version: "1.0.0"  # 版本号
    contact:  # 联系人信息
      name: "开发团队"
      email: "dev@example.com"
  servers:  # 接口服务器地址（可选，默认使用当前服务地址）
    - url: "http://localhost:8080"
      description: "开发环境"

方式 2：通过 Java 代码配置（更灵活）

创建配置类SpringDocConfig.java，自定义 OpenAPI 对象：

import io.swagger.v3.oas.models.OpenAPI;
import io.swagger.v3.oas.models.info.Contact;
import io.swagger.v3.oas.models.info.Info;
import io.swagger.v3.oas.models.servers.Server;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import java.util.ArrayList;
import java.util.List;

@Configuration
public class SpringDocConfig {

    // 自定义OpenAPI文档信息
    @Bean
    public OpenAPI customOpenAPI() {
        // 配置服务器地址
        List<Server> servers = new ArrayList<>();
        servers.add(new Server().url("http://localhost:8080").description("开发环境"));
        servers.add(new Server().url("http://test.example.com").description("测试环境"));

        // 配置联系人信息
        Contact contact = new Contact()
                .name("后端开发组")
                .email("dev@example.com")
                .url("https://example.com");

        // 配置文档基本信息
        Info info = new Info()
                .title("用户管理系统API文档")
                .description("基于SpringDoc+OpenAPI 3.0的RESTful API文档")
                .version("v1.0.0")
                .contact(contact);

        return new OpenAPI().info(info).servers(servers);
    }
}

步骤 4：编写实体类（用注解增强字段说明）

使用@Schema注解描述实体类及字段，让文档更清晰。

创建User.java（实体类）：

package com.yqd.entity;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "用户实体类")  // 描述实体类
public class User {
    @Schema(description = "用户ID", example = "1001", required = false)
    // example：示例值；required：是否必传；hidden：是否隐藏字段
    private Long id;

    @Schema(description = "用户名", example = "张三", required = true)
    private String username;

    @Schema(description = "年龄", example = "25", minimum = "1", maximum = "120")
    private Integer age;

    @Schema(description = "邮箱", example = "zhangsan@example.com", hidden = true)
    private String email;
}

步骤 5：编写 Controller（用注解描述接口）

使用 SpringDoc 注解（@Tag、@Operation等）描述接口功能、参数等，生成更详细的文档。

创建UserController.java：

package com.yqd.controller;

import com.yqd.entity.User;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/users")
@Tag(name = "用户管理接口", description = "包含用户查询、新增、修改等操作")  // 描述Controller（分组）
public class UserController {

    /**
     * 根据ID查询用户
     */
    @GetMapping("/{id}")
    @Operation(
            summary = "查询用户详情",  // 接口简短描述
            description = "通过用户ID获取完整信息，ID为数字类型",  // 详细说明
            tags = {"用户查询"}  // 可额外指定标签（用于分组）
    )
    public User getUserById(
            @Parameter(description = "用户ID", required = true, example = "1001")
            @PathVariable Long id
    ) {
        // 模拟查询
        User user = new User();
        user.setId(id);
        user.setUsername("张三");
        user.setAge(25);
        return user;
    }

    /**
     * 新增用户
     */
    @PostMapping
    @Operation(summary = "新增用户", description = "传入用户信息创建新用户，用户名必填")
    public String addUser(
            @Parameter(description = "用户对象", required = true)
            @RequestBody User user
    ) {
        return "新增成功：" + user.getUsername();
    }

    /**
     * 修改用户年龄
     */
    @PutMapping("/{id}/age")
    @Operation(summary = "修改用户年龄", description = "根据ID更新用户年龄，年龄需在1-120之间")
    public String updateAge(
            @Parameter(description = "用户ID", required = true)
            @PathVariable Long id,
            @Parameter(description = "新年龄", required = true, example = "30")
            @RequestParam Integer age
    ) {
        return "用户" + id + "的年龄已更新为：" + age;
    }
}

核心注解说明：

注解	作用范围	关键属性及说明
`@Tag(name, description)`	Controller 类	`name`：分组名称；`description`：分组功能说明
`@Operation(summary, description)`	方法	`summary`：接口标题；`description`：接口详细说明
`@Parameter(description, required)`	方法参数	`description`：参数含义；`required`：是否必传
`@Schema(description, example)`	实体类 / 字段	`description`：字段说明；`example`：示例值
`@Hidden`	方法 / 类	标记后，接口或类不会在文档中显示

步骤 6：启动类

@SpringBootApplication
public class SpringBootSwaggerDemo {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootSwaggerDemo.class, args);
    }
}

步骤 7：启动项目并访问 Swagger UI

启动 Spring Boot 应用（直接运行主类XXXApplication.java）。
访问 Swagger UI 界面：地址：http://localhost:8080/swagger-ui.html（端口号与application.yml中配置一致）。

界面功能说明：
- 顶部：显示文档标题、版本、联系人等信息（来自openapi.info配置）。
- 左侧：按@Tag分组显示所有接口，可搜索接口。
- 中间：点击接口可查看详情（请求方式、参数、返回值类型）。
- 调试：点击接口右侧的Try it out，填写参数后点击Execute，即可发送请求并查看响应结果。

五、进阶配置与问题解决

1. 控制 SpringDoc 仅在开发 / 测试环境启用

生产环境需关闭 API 文档，避免接口暴露。通过@Profile注解实现：

import org.springframework.context.annotation.Profile;
// ... 其他导入

@Configuration
@Profile({"dev", "test"})  // 仅在dev/test环境生效，prod环境不加载
public class SpringDocConfig {
    // ... 配置内容不变
}

2. 集成 Spring Security 时开放 Swagger 资源

若项目使用 Spring Security，需在安全配置中允许访问 Swagger 相关路径，否则会被拦截：

import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;

@Configuration
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
                // 开放Swagger UI及API文档路径
                .antMatchers(
                    "/swagger-ui.html",    // Swagger UI页面
                    "/swagger-ui/**",      // Swagger UI静态资源
                    "/v3/api-docs/**",     // OpenAPI文档JSON数据
                    "/api-docs/**"         // 自定义的API文档路径（若配置）
                ).permitAll()
                // 其他接口需认证
                .anyRequest().authenticated()
                .and().csrf().disable();  // 关闭CSRF，方便调试
    }
}

3. 解决中文乱码问题

若 Swagger UI 中中文显示乱码，检查以下配置：

IDEA 中设置File Encodings为UTF-8（File → Settings → Editor → File Encodings）。

pom.xml中添加编码配置：

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

4.Spring Boot 3.x 的适配差异

若使用 Spring Boot 3.x，需注意：

JDK 必须为 17 及以上。

SpringDoc 依赖改为：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
</dependency>

配置文件中springdoc的部分属性名变化（如paths-to-scan改为packages-to-scan），建议参考官方文档。

六、总结

Spring Boot 整合 SpringDoc 的核心流程：

添加springdoc-openapi-ui依赖。
（可选）通过配置文件或代码自定义文档信息。
使用@Tag、@Operation、@Schema等注解增强接口和实体类描述。
启动项目，访问/swagger-ui.html即可查看和调试 API。

posted @ 2025-10-24 10:23 碧水云天4 阅读(15) 评论(0) 收藏举报

刷新页面返回顶部

碧水云天4

SpringBoot整合SpringDoc

SpringBoot整合SpringDoc

一、SpringDoc 是什么？

二、为什么选择 SpringDoc？

三、环境准备

四 实现过程

步骤 1：创建 Spring Boot 项目

步骤 2：添加 SpringDoc 依赖

步骤 3：基础配置（自定义文档信息）

方式 1：通过 application.yml 配置（推荐）

方式 2：通过 Java 代码配置（更灵活）

步骤 4：编写实体类（用注解增强字段说明）

步骤 5：编写 Controller（用注解描述接口）

步骤 6：启动类

步骤 7：启动项目并访问 Swagger UI

五、进阶配置与问题解决

1. 控制 SpringDoc 仅在开发 / 测试环境启用

2. 集成 Spring Security 时开放 Swagger 资源

3. 解决中文乱码问题

4.Spring Boot 3.x 的适配差异

六、总结

公告

四实现过程