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文档信息@Beanpublic 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 {@Overrideprotected 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。
