RuoYi-Vue 集成 Swagger 3.0 接口文档配置指南

【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统，同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue

前后端联调最磨人的环节，往往是拿着一半过期的接口文档反复手动拼 URL：参数名对不上、字段类型对不上，前端问一句、后端翻一遍代码答一句。把 RuoYi-Vue 接上 Swagger 3.0 接口文档，这套协作方式可以直接省掉——接口从代码注解里自动生成，文档跟着代码走，不存在"写一半就过期"。跟着本文做，收益能落到三件具体的事上：3 个配置类完成全部接入、启动后 1 个 URL 在线调试所有接口、每个方法加 1 个注解即可让接口出现在文档里。

为什么是 Swagger 3.0

它把文档从"手写"变成"自动生成"：接口定义在代码里，文档从代码里长出来，天然不过期。前后端解耦也很实在——后端把 OpenAPI 3.0 规范甩给前端，对方就能并行开发，不用再追着人问参数。团队内部还多了一份统一规范，字段命名、错误码在文档页面上肉眼可见。RuoYi-Vue 的接入恰好只用三个配置类加一段 yaml，下面按动手顺序来。

🛠️ 动手配置：3 个配置类 + 1 段 yaml

接入只涉及四处：SwaggerConfig（文档信息与全局认证）、application.yml的 springdoc 段（扫描策略）、SecurityConfig（放行）、ResourcesConfig（UI 资源映射）。按下面的顺序改完，跑起来即可验证。

1. 让文档页知道"这份文档叫什么"

SwaggerConfig在 ruoyi-admin 模块的 core/config 包 下，apiInfo()决定文档首页展示的标题、描述和版本，直接取ruoyiConfig里的系统名和版本号，升级系统时文档版本自动跟着走，不用手动维护：

@Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) // 关键：OAS_30 指定 OpenAPI 3.0 规范 .enable(enabled) // 读配置里的 swagger.enabled .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build() .securitySchemes(securitySchemes()) .securityContexts(securityContexts()) .pathMapping(pathMapping); } private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("标题：若依管理系统_接口文档") .contact(new Contact(ruoyiConfig.getName(), null, null)) .version("版本号:" + ruoyiConfig.getVersion()) .build(); }

2. 只把你愿意暴露的接口交给文档

扫描策略就一行核心：withMethodAnnotation(ApiOperation.class)。它让 Swagger 只收集带@ApiOperation注解的方法，没标注的接口一律不出现在文档里——相当于给每个接口留了个"是否公开"的开关，哪些能对外直接看注解就懂，不用翻文档目录。

.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) // 关键：只扫带注解的方法 .paths(PathSelectors.any())

3. 给所有接口挂上 Token 认证

Swagger UI 右上角的 Authorize 按钮靠这一段配置生成：声明一个名为Authorization的 API Key、放在请求头里，再让所有路径都引用它。登录后台拿到 token 后粘贴一次，后续所有调试请求自动带头，不用每次手动复制。

private List<SecurityScheme> securitySchemes() { List<SecurityScheme> apiKeyList = new ArrayList<>(); apiKeyList.add(new ApiKey("Authorization", "Authorization", In.HEADER.toValue())); // 关键：API Key 放请求头 return apiKeyList; } private List<SecurityContext> securityContexts() { List<SecurityContext> securityContexts = new ArrayList<>(); securityContexts.add(SecurityContext.builder() .securityReferences(defaultAuth()) .operationSelector(o -> o.requestMappingPattern().matches("/.*")) // 关键：全部路径都要认证 .build()); return securityContexts; }

4. 把 UI 页面放行到 Security 之外

项目有 Spring Security，swagger-ui相关路径不放行会被 401 拦下；放行之后，UI 的静态资源还要靠ResourcesConfig从 classpath 里映射出来，两者配合才算齐活。

// SecurityConfig.configure(HttpSecurity) .antMatchers("/swagger-ui.html", "/swagger-resources/**", "/webjars/**", "/*/api-docs").permitAll()

// ResourcesConfig.addResourceHandlers registry.addResourceHandler("/swagger-ui/**") // 关键：UI 页面路径 .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");

✅ 写一个注解接口验证效果

在任意 Controller 加一个最小示例，一个 GET 方法加@ApiOperation就够：

@ApiOperation("获取用户信息") @ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "int", paramType = "path") @GetMapping("/info/{id}") public AjaxResult info(@PathVariable("id") Integer id) { return AjaxResult.success(id); }

启动后访问http://localhost:8080/swagger-ui/index.html，列表里能看到这个接口，点 Try it out 直接在线调通，说明整条链路已通。

🧯 避坑 & 快速排查

• 生产环境记得把swagger.enabled设为 false（或移除 swagger-ui 依赖），接口明细对外是安全隐患。
• 配置了网关 context-path 却忘了对齐pathMapping，现象是 UI 打得开、点接口却 404——两者前缀必须一致。
• springfox 与 Spring Boot 2.6+ 存在路径解析器不兼容问题，启动时若看到PathPatternParser相关报错，多半是版本没对上，本文的 RuoYi-Vue 配置已按兼容版本处理。

跑通之后可以顺手做两件事：用group-configs或@Api(tags = ...)把业务接口按模块分组，文档目录立刻清爽；嫌原生 UI 弱就接入 Knife4j，离线导出文档和在线调试都会更强。

【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统，同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue