Spring Boot 3.5.x 实战：SpringDoc 2 与 Swagger3 的深度集成与配置优化

1. 为什么在Spring Boot 3.5.x时代我坚定地选择了SpringDoc 2如果你和我一样是从Spring Boot 2.x时代一路升级上来的老开发者那你肯定对Swagger 2.x和它的老朋友springfox-boot-starter不陌生。当年它几乎是Spring Boot项目生成API文档的“标配”。但是当我开始接触Spring Boot 3.x特别是最新的3.5.x版本时我发现老伙计有点“水土不服”了。项目一启动各种类找不到、注解不兼容的报错接踵而至。这其实不是springfox的错而是技术栈的必然升级。Spring Boot 3.x是一个重大的里程碑它全面转向了Jakarta EE 9的命名空间。简单来说以前我们熟悉的javax.servlet、javax.validation这些包名现在统统变成了jakarta.servlet、jakarta.validation。springfox的核心版本3.0.0发布于2020年它构建在旧的javax体系和Swagger 2.0规范之上自然无法适配这个新世界。强行整合只会让你陷入无尽的依赖冲突和兼容性泥潭。这时候SpringDoc就像一位专为新版本打造的“救星”走进了我的视野。它不是对springfox的简单修补而是一个全新的、为OpenAPI 3.0规范和Spring Boot 3原生设计的库。我选择它的理由非常实在第一它官方支持Jakarta EE与Spring Boot 3.x无缝集成启动即用几乎没有兼容性烦恼。第二它直接拥抱了更强大、更标准的OpenAPI 3.0规范这意味着生成的文档描述能力更强能更好地支持Webhook、回调、链路等现代API特性。第三它的配置方式非常“Spring化”既支持application.yml的优雅配置也支持通过Bean定义进行编程式定制符合Spring开发者的直觉。所以在Spring Boot 3.5.x的项目里我的建议非常明确忘掉springfox直接拥抱SpringDoc 2。这不仅是版本升级更是一次技术栈的现代化换代。它能让你在享受Spring Boot 3.x新特性的同时获得一份更专业、更强大的API文档。2. 5分钟快速上手基础依赖与环境搭建说干就干让我们从一个干净的Spring Boot 3.5.x项目开始。我习惯用Spring Initializrstart.spring.io快速生成项目骨架选择最新的Spring Boot 3.5.x版本依赖只需要勾选Spring Web就行。项目生成后打开pom.xml文件关键的一步来了添加SpringDoc的依赖。这里有个新手特别容易踩的坑一定要注意依赖的坐标。网上很多老教程会提到springdoc-openapi-ui但在Spring Boot 3.x中我们更应该使用starter依赖它能获得最好的自动配置体验。对于最常用的Web MVC项目核心依赖就这一个dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.6.0/version !-- 请检查并使用最新版本 -- /dependency对你没看错就这一个。这个starter-webmvc-ui依赖是个“全家桶”它内部已经包含了生成OpenAPI规范JSON的核心模块和渲染Swagger UI界面的所有必要组件。添加之后你甚至不需要写任何配置代码SpringDoc的自动配置就已经生效了。现在你可以启动你的Spring Boot应用。启动成功后打开浏览器访问两个默认地址OpenAPI规范文档机器可读http://localhost:8080/v3/api-docsSwagger UI交互界面人类可读http://localhost:8080/swagger-ui/index.html如果一切顺利访问第一个链接你会看到一个庞大的JSON结构这就是你的API按照OpenAPI 3.0规范生成的完整描述。访问第二个链接一个熟悉的、可交互的Swagger UI界面应该已经呈现在你面前了它会自动解析/v3/api-docs的数据并展示出来。是不是非常简单SpringDoc的“开箱即用”特性在这里体现得淋漓尽致。当然现在界面上可能还没有内容因为我们还没有写任何Controller。别急我们先来把这个基础环境配置得更顺手一些。2.1 基础配置让文档更符合你的项目虽然开箱即用很好但默认的路径和文档信息可能不符合我们项目的需求。我习惯在application.yml或application.properties里进行一些基础配置让文档更“像”我们自己的东西。springdoc: api-docs: path: /api-docs # 自定义OpenAPI JSON的访问路径 enabled: true # 是否启用生产环境可关闭 swagger-ui: path: /swagger-ui.html # 自定义UI界面路径兼容老习惯 enabled: true # 是否启用UI operations-sorter: method # 接口按HTTP方法排序 tags-sorter: alpha # 标签按字母排序 display-request-duration: true # 显示模拟请求的耗时我来解释一下这几个配置。api-docs.path和swagger-ui.path允许你自定义访问路径比如从默认的/v3/api-docs改成更简短的/api-docs或者把UI路径改成经典的/swagger-ui.html。operations-sorter和tags-sorter能帮你整理界面让接口列表看起来更规整。display-request-duration是个很实用的小功能当你在UI界面上点击“Try it out”测试接口时它会显示请求花了多长时间对性能有个直观感受。2.2 编写第一个带文档的Controller光有架子不行我们得有点内容。创建一个简单的Controller并开始使用SpringDoc的注解。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/demo) Tag(name 演示模块, description 用于演示SpringDoc基础功能的接口) public class DemoController { GetMapping(/hello) Operation(summary 问好接口, description 向传入的用户名问好) public String sayHello( Parameter(description 用户名, example 张三, required true) RequestParam String name) { return Hello, name !; } }重启应用再次打开Swagger UI界面http://localhost:8080/swagger-ui.html你会看到多了一个叫“演示模块”的分组里面有一个“问好接口”。点开它参数name的描述和示例值都清晰可见你可以直接在里面输入值并点击“Execute”进行测试。到这里一个最基础的、可用的API文档系统就已经搭建完成了。整个过程可能连5分钟都不用这就是SpringDoc在Spring Boot 3.5.x下的开发效率。3. 深度定制打造专业级的API文档基础功能有了但如果你想生成一份能让前端、测试甚至客户都交口称赞的专业文档就需要进行深度定制。SpringDoc的强大之处就在于它提供了极其丰富的配置项和注解体系让你能精细地控制文档的每一个细节。3.1 使用配置类定义全局文档信息通过application.yml可以做一些基础设置但文档的标题、描述、版本、许可证等全局信息最好通过一个Java配置类来定义。这更灵活也能利用编程的优势。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.info.License; import io.swagger.v3.oas.models.servers.Server; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; Configuration public class OpenApiConfig { Bean public OpenAPI customOpenAPI() { return new OpenAPI() // 定义API的基本信息 .info(new Info() .title(电商平台后端API文档) .description(这是基于Spring Boot 3.5.x和SpringDoc 2构建的详细接口文档。包含用户、商品、订单等所有模块。) .version(v1.2.0) .contact(new Contact() .name(技术支撑团队) .email(dev-supportexample.com) .url(https://internal.example.com)) .license(new License() .name(Apache 2.0) .url(http://www.apache.org/licenses/LICENSE-2.0.html))) // 可以定义多个服务器地址适用于测试、预发布、生产等不同环境 .addServersItem(new Server().url(http://localhost:8080).description(本地开发环境)) .addServersItem(new Server().url(https://api.staging.example.com).description(预发布环境)) .addServersItem(new Server().url(https://api.example.com).description(生产环境)); } }这个OpenAPIBean是文档的“总设计师”。Info对象定义了文档的元数据让使用者一眼就知道这是谁、什么版本、怎么联系。Server对象的配置非常实用特别是在微服务或多环境场景下。前端开发者在Swagger UI右上角可以直接切换不同的服务器地址一键从测试本地接口切换到测试线上接口大大提升了联调效率。3.2 精细化注解让模型和参数说明更清晰Swagger 3OpenAPI 3.0的注解体系比Swagger 2更加强大和精细。用好这些注解你的DTO数据传输对象和参数在文档里会变得一目了然。模型类DTO/VO注解以前用ApiModel和ApiModelProperty现在统一用Schema。import io.swagger.v3.oas.annotations.media.Schema; Schema(description 用户创建请求数据传输对象) public class UserCreateDTO { Schema( description 用户登录名必须唯一长度4-20位, example zhangsan, requiredMode Schema.RequiredMode.REQUIRED, minLength 4, maxLength 20 ) private String username; Schema( description 用户邮箱地址, example userexample.com, requiredMode Schema.RequiredMode.REQUIRED, pattern ^[A-Za-z0-9_.-](.)$ // 可添加正则表达式验证模式 ) private String email; Schema( description 用户年龄, example 25, minimum 0, maximum 150, defaultValue 18 ) private Integer age; Schema( description 用户角色列表, example [\USER\, \EDITOR\], allowableValues {USER, ADMIN, EDITOR} // 定义允许的值 ) private ListString roles; // 省略 getter/setter 和构造方法 }Schema注解功能非常丰富。除了基本的描述和示例你还能定义字段是否必填requiredMode、长度限制minLength/maxLength、数值范围minimum/maximum、默认值defaultValue、甚至正则表达式pattern和枚举值allowableValues。这些信息不仅会展示在文档里在一些支持OpenAPI规范的前端代码生成工具中还能直接生成对应的校验代码。接口参数与响应注解在Controller层我们可以更精确地描述每个接口。PostMapping Operation( summary 创建新用户, description 接收用户信息并创建新用户账户。系统将自动发送验证邮件。, tags {用户管理} // 可以覆盖类级别的Tag ) ApiResponses(value { ApiResponse( responseCode 201, description 用户创建成功, content Content( mediaType application/json, schema Schema(implementation UserVO.class) // 明确指定成功响应体 ) ), ApiResponse( responseCode 400, description 请求参数无效如用户名已存在、邮箱格式错误等, content Content( mediaType application/json, schema Schema(implementation ErrorResponse.class) // 明确指定错误响应体 ) ), ApiResponse( responseCode 500, description 服务器内部错误 ) }) public ResponseEntityUserVO createUser(Valid RequestBody UserCreateDTO userCreateDTO) { // 业务逻辑... }这里用到的ApiResponses和ApiResponse是提升文档专业度的关键。它明确声明了接口在不同情况下的返回状态码、描述以及响应体的数据结构。前端开发者一看就知道调用成功201会返回UserVO参数错误400会返回ErrorResponse而不是靠猜测。这能极大减少沟通成本。Parameter注解同样可以用于详细描述RequestParam、PathVariable等参数。4. 高级配置与生产环境优化当项目逐渐复杂或者需要部署到生产环境时我们还需要考虑更多。SpringDoc提供了一系列高级配置来应对这些场景。4.1 分组与多版本API管理在一个大型项目中可能有面向内部管理的API、面向客户端的API、面向第三方集成的API它们混杂在一起会让文档变得臃肿不堪。SpringDoc的分组Grouping功能就是解决这个问题的利器。我们可以通过配置将不同包路径下的Controller划分到不同的文档组中。springdoc: group-configs: - group: admin-api # 组名 paths-to-match: /admin/** # 匹配以/admin开头的接口路径 packages-to-scan: com.example.project.admin.controller # 扫描的包 - group: client-api paths-to-match: /api/v1/** packages-to-scan: com.example.project.client.controller - group: public-api paths-to-scan: com.example.project.public.controller配置完成后访问文档的方式会发生变化默认组所有接口/v3/api-docs和/swagger-ui.htmlAdmin组/v3/api-docs/admin-api和/swagger-ui.html?groupadmin-apiClient组/v3/api-docs/client-api和/swagger-ui.html?groupclient-api这样不同角色的开发者只需要关注自己负责的接口文档界面清晰查找效率高。对于API版本管理如/api/v1/,/api/v2/也可以利用这个分组功能来实现。4.2 安全配置集成JWT/Basic认证API文档如果完全公开可能会暴露内部接口信息。SpringDoc允许我们为Swagger UI界面本身添加安全认证或者展示需要认证的API该如何调用。为Swagger UI界面添加基础认证这可以防止无关人员随意访问文档地址。springdoc: swagger-ui: enabled: true path: /docs config-url: /v3/api-docs/swagger-config urls: - url: /v3/api-docs name: 全部API # 关键配置启用HTTP Basic认证 try-it-out-enabled: true # 通过配置类或Security配置来保护 /docs, /v3/api-docs 等端点更常见的做法是结合Spring Security来保护这些端点。你可以配置Security规则只允许特定IP或拥有特定角色的用户访问/docs和/api-docs/**路径。在文档中展示API安全需求如果你的接口使用了JWT、OAuth2等认证方式你可以在全局配置中声明这样前端在Swagger UI上测试时就可以先“Authorize”设置Token然后发出的请求会自动带上认证头。Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(...) // 添加安全方案定义 .components(new Components() .addSecuritySchemes(bearer-jwt, new SecurityScheme() .type(SecurityScheme.Type.HTTP) .scheme(bearer) .bearerFormat(JWT) .description(请在此处输入有效的JWT Token))) // 全局应用安全方案如果所有接口都需要 .addSecurityItem(new SecurityRequirement().addList(bearer-jwt)); }这样配置后Swagger UI界面会出现一个“Authorize”按钮点击输入JWT Token后所有接口的测试请求都会自动在Header中加上Authorization: Bearer 你的Token。4.3 生产环境部署策略直接将Swagger UI暴露在生产环境是危险的。我通常采用以下策略基于Profile控制在application-prod.yml中彻底关闭Swagger UI和API Docs的生成。springdoc: api-docs: enabled: false swagger-ui: enabled: false这样在生产环境根本不会生成相关端点最安全。构建时生成静态文档在CI/CD流水线中使用springdoc-openapi-maven-plugin插件在测试或构建阶段生成一份OpenAPI规范的JSON/YAML文件。plugin groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-maven-plugin/artifactId version1.8.0/version executions execution phaseintegration-test/phase goals goalgenerate/goal /goals /execution /executions configuration apiDocsUrlhttp://localhost:${server.port}/v3/api-docs/apiDocsUrl outputFileNameopenapi.json/outputFileName outputDir${project.build.directory}/api-docs/outputDir /configuration /plugin然后可以将这份静态的openapi.json文件交给专门的API文档管理平台如Redocly、Stoplight去渲染和托管或者提供给前端团队用于生成SDK。这样既保证了文档的及时更新又隔离了生产环境。内网访问控制如果必须在生产环境保留文档例如用于内部监控或调试务必通过Spring Security、网络防火墙等手段将其访问权限严格限制在内网或特定管理员范围。5. 常见问题排查与性能调优在实际使用中你可能会遇到一些小问题。这里分享几个我踩过的坑和解决方案。问题一接口/模型没有在文档中显示这是最常见的问题。首先检查你的Controller是否在Spring Boot的应用扫描路径下并且被正确加载。其次确认你没有在配置中通过springdoc.packages-to-scan或springdoc.paths-to-match错误地排除了你的接口。一个快速排查的方法是直接访问/v3/api-docs在返回的JSON里全局搜索你的接口路径或模型类名看看是否存在。问题二Swagger UI页面加载缓慢或空白这通常是因为项目中的接口和模型非常多生成的OpenAPI JSON文件过大超过1MB甚至更大导致UI加载和解析变慢。优化方法有几个启用分组如上所述将接口按模块拆分每个组只加载一部分接口。配置模型深度有些复杂的嵌套对象如循环引用会导致文档爆炸式增长。可以在配置中限制模型的递归深度。springdoc: model-converters: pageable-converter: enabled: true # 优化Spring Data Pageable对象的展示 default-flat-param-object: false # 限制模型深度 max-depth: 5排除不必要的端点Spring Boot默认的健康检查端点/actuator/**也会被扫描。如果不需要可以排除它们。springdoc: paths-to-exclude: - /actuator/** - /error问题三自定义的全局响应包装器导致文档混乱很多项目会用一个统一的ResultT或ResponseT类包装所有接口的响应。这会导致Swagger文档里所有接口的响应体都变成了Result«UserVO»而无法直接看到UserVO的结构细节。解决方法是使用RestControllerAdvice和ResponseBody注解在响应序列化时进行包装而不是让每个Controller方法都返回Result。这样Controller方法可以直接返回UserVO文档就能清晰展示真实数据结构而统一包装由切面处理对文档生成无干扰。问题四如何为枚举类型生成更好的描述默认情况下枚举在文档里只会显示其名称。你可以为枚举值添加Schema注解来提供描述。public enum UserStatus { Schema(description 已注册待激活) PENDING, Schema(description 已激活正常使用) ACTIVE, Schema(description 已被管理员禁用) DISABLED }关于性能SpringDoc在启动时会扫描所有Controller和模型类对于超大型项目数百个Controller可能会轻微影响应用启动时间增加几秒。这在开发阶段完全可以接受。如果确实成为问题可以仔细规划packages-to-scan的范围避免扫描不必要的包。在生产环境如前所述直接关闭文档生成功能即可不会有任何运行时性能开销。从最初的依赖引入到基础配置再到深度定制和高级优化SpringDoc 2在Spring Boot 3.5.x项目中的集成是一条清晰且强大的路径。它不仅仅是一个文档生成工具更是推动团队遵循API设计规范、提升前后端协作效率的催化剂。花点时间配置好它在后续的开发和维护中你会不断收获它带来的便利。