SpringBoot整合SpringDoc

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 的核心优势：

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

1. 启动 Spring Boot 应用（直接运行主类XXXApplication.java）。

2. 访问 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 的核心流程：

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