一、背景与痛点目前项目现状老平台基于 Freemarker 传统架构新业务模块采用 Spring Boot 3 Vue 前后端分离模式前端开发总吐槽接口不清晰。以往团队一直用 Apipost、Torna 维护接口文档踩坑无数接口字段、必填项标注混乱前后端对接经常扯皮第三方文档工具无法在线调试还要手动复制参数跨域、Token 校验问题频发前端总以 “文档不准” 甩锅后端文档和代码不同步代码改了文档忘改久而久之形同虚设。实际诉求很简单一套和代码强同步、支持在线调试、有权限拦截、能复用老平台登录态的一体化 API 文档方案。二、技术选型对比Spring Boot 3 已全面弃用 Springfox传统 Swagger2 直接兼容不了先做方案对比表格技术方案优点缺点选型Swagger2 Springfox生态老牌、使用习惯成熟早已停更不兼容 Spring Boot3、Jakarta 规范❌ 放弃Torna 接口文档代码无强侵入、集中管理依赖额外部署、跨域问题多、前端适配一般❌ 放弃SpringDoc Knife4j兼容 OpenAPI3、适配 Boot3、界面美观、支持分组、权限易控需要少量注解规范✅ 最终选用最终敲定SpringDoc Knife4j 4.5.0适配 Spring Boot3一站式解决 API 文档、在线调试、登录态复用三大问题。三、实战完整落地步骤3.1 引入 Maven 依赖Spring Boot 3.x 必须引入jakarta版本不要引旧的 javax 包xml!-- Knife4j 整合SpringDoc 适配SpringBoot3 -- dependency groupIdcom.github.xiaoymin/groupId artifactIdknife4j-openapi3-jakarta-spring-boot-starter/artifactId version4.5.0/version /dependency3.2 全局配置类分组 文档基础信息支持按模块、按接口路径做多文档分组方便前后端按业务查看java运行import io.swagger.v3.oas.annotations.info.Contact; import io.swagger.v3.oas.annotations.info.Info; import io.swagger.v3.oas.models.OpenAPI; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.web.servlet.config.annotation.WebMvcConfigurer; import springdoc.group.GroupedOpenApi; Configuration public class Knife4jConfig implements WebMvcConfigurer { /** * 系统管理模块接口分组 */ Bean public GroupedOpenApi adminApi() { return GroupedOpenApi.builder() .group(系统管理模块) .packagesToScan(com.xxx.system.controller) .pathsToMatch(/admin/**) .build(); } /** * 业务模块接口分组 */ Bean public GroupedOpenApi bizApi() { return GroupedOpenApi.builder() .group(业务业务模块) .packagesToScan(com.xxx.biz.controller) .pathsToMatch(/biz/**) .build(); } /** * 文档全局基础信息 */ Bean public OpenAPI customOpenAPI() { return new OpenAPI() .info(new Info() .title(项目统一API接口文档) .version(V1.0) .contact(new Contact().name(后端研发)) .description(基于SpringBoot3 Knife4j 自动生成接口文档)); } }3.3 标准注解使用规范控制器层注解java运行import io.swagger.v3.oas.annotations.Operation; import io.swagger.v3.oas.annotations.tags.Tag; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; RestController RequestMapping(/admin/user) Tag(name 系统用户管理) public class UserController { Operation(summary 用户分页列表查询) GetMapping(/list) public ResultPageResultUserVO listUser(UserQuery query) { // 业务逻辑省略 } }实体类参数注解用Schema描述字段、示例值、是否必填java运行import io.swagger.v3.oas.annotations.media.Schema; import lombok.Data; Data Schema(description 用户查询条件) public class UserQuery { Schema(description 用户姓名-模糊查询, example 张三) private String userName; Schema(description 账号状态 0-禁用 1-正常, allowableValues {0,1}, example 1) private Integer status; Schema(description 手机号, requiredMode Schema.RequiredMode.REQUIRED, example 13800138000) private String phone; }requiredMode REQUIRED标记接口必填字段文档自动标红example给调试提供默认示例值前端直接可用。3.4 隐藏内部接口避坑很多人直接用Hidden注解容易出现整个 Controller 接口全部消失的 BUG。推荐标准写法只隐藏单个接口不影响其他接口展示java运行Operation(summary 内部回调接口文档隐藏, hidden true) PostMapping(/inner/callback) public Result callback() { // 内部逻辑 }3.5 权限控制未登录禁止访问文档常规做法是在 Spring Security 放行文档路径任何人都能看不安全。改造思路取消文档路径匿名放行删除 SecurityConfig 中如下配置java运行// 删掉这段匿名放行 // .requestMatchers(/doc.html,/v3/api-docs/**,/swagger-ui/**).permitAll()效果验证浏览器无痕模式直接访问项目地址/doc.html自动 302 重定向到登录页必须登录后才能查看接口文档。3.6 集成老平台复用已有登录态老平台基于 Freemarker 模板直接在顶部菜单 / 个人下拉菜单中加入文档入口html预览a classdropdown-item href/doc.html target_blank i classfas fa-file-alt/i 接口文档 /a原理从老平台菜单点击跳转自动携带当前登录 Cookie无需二次登录直接进入文档页面完美复用现有登录体系。配置完成并部署上线后即可直接访问接口文档首页分组管理、接口统计、必填字段标注全部生效支持在线调试且已接入权限控制复用老平台登录态无需额外登录即可查看文档四、实战踩坑记录汇总Hidden 导致整个控制器接口消失解决弃用类上 Hidden改用Operation(hidden true)只隐藏单个接口。配置分组后接口不显示解决核对packagesToScan包路径 和pathsToMatch接口前缀必须严格对应。访问文档 401 不跳转登录页解决登录接口、静态资源务必在 Security 中正常放行配置登录跳转规则。文档在线调试跨域 / 无权限解决必须保持登录状态携带登录 Cookie 再调试和业务接口鉴权逻辑统一。五、总结Spring Boot3 不要再用老旧 Swagger2SpringDoc Knife4j 是最优解隐藏接口优先用Operation(hidden true)避开全局隐藏坑接口文档一定要做登录拦截不能公开匿名访问嵌入老平台菜单复用登录态省去单独做文档登录模块极简高效代码注解即文档一改全改彻底告别手动维护 API 文档、前后端扯皮的问题。一套规范的自动 API 文档不光是方便前端更是规范接口、划清责任、减少后期维护成本把重复体力活交给框架自己专注核心业务和架构沉淀。本文是《技术底稿》系列第 28 篇记录 Spring Boot3 整合 Knife4jSpringDoc 完整实战包含依赖引入、分组配置、注解规范、接口隐藏避坑、权限拦截及老平台登录态复用全流程落地可直接复用到现有项目解决手写 API 文档、前后端对接扯皮的日常痛点。