RuoYi-Vue Swagger3.0 接口文档配置指南：4 步生成专业 API 文档

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

先看效果 ✨

配置完成后启动 RuoYi-Vue 项目，打开http://localhost:8080/swagger-ui/index.html，接口文档就在页面上自动生成：接口按模块分组、请求参数、返回结构一目了然，每个接口还带 Try it out 按钮，可以直接在线调试。

前端不用再追着要参数说明，后端也不用手写接口文档，文档从代码里长出来，永远不会过期。

为什么值得配

手写接口文档最大的问题是跟不上代码：接口一改，文档就旧，前端拿到的永远是过期版本。

接入 Swagger3.0（OpenAPI 3.0）后，文档和代码同仓库维护，注解即文档。更实用的是，token 粘进去就能在页面直接调真实接口，比再开一个 Postman 方便。

第 1 步：确认开关与扫描范围 ⚙️

做什么：打开 application.yml，确认文档开关已打开，并决定哪些控制器包对外展示。

springdoc: swagger-ui: enabled: true # 文档页面开关 path: /swagger-ui.html # 文档入口地址 group-configs: - group: 'default' packages-to-scan: com.ruoyi.web.controller.tool

enabled决定页面是否可用；packages-to-scan决定展示范围，RuoYi-Vue 默认只开放tool测试模块，系统接口不会暴露给外面。

第 2 步：核心配置类怎么写

做什么：SwaggerConfig.java 定义了两个 Bean，一个负责文档信息，一个负责 Token 认证。

RuoYi-Vue 3.9.x 仓库用的是 springdoc-openapi，也就是 OpenAPI 3.0 的官方实现：

@Bean public OpenAPI customOpenApi() { return new OpenAPI() .components(new Components() .addSecuritySchemes("apikey", securityScheme()) .addSecurityItem(new SecurityRequirement().addList("apikey"))) .info(getApiInfo()); // 标题、描述、版本号 }

OpenAPI对象相当于 springfox 时代的Docket，旧写法的DocumentationType.OAS_30声明在这里由 springdoc 隐式满足，getApiInfo()则对应旧的ApiInfoBuilder。如果你维护的还是老 springfox 版本，等价写法是：

new Docket(DocumentationType.OAS_30) .apiInfo(new ApiInfoBuilder().title("RuoYi-Vue 接口文档").build())

Token 认证单独一个 Bean：

@Bean public SecurityScheme securityScheme() { return new SecurityScheme() .type(SecurityScheme.Type.APIKEY) .name("Authorization") // 请求头名称 .in(SecurityScheme.In.HEADER) .scheme("Bearer"); }

效果是文档页面右上角出现 Authorize 按钮，填入 token 后，每次请求都会自动携带Authorization请求头，与 RuoYi-Vue 的 JWT 认证方式完全一致。

第 3 步：放行静态资源与安全拦截

做什么：文档页是静态资源，接口数据来自/v3/api-docs端点，两者都要放行，否则会被 Spring Security 拦下。

ResourcesConfig.java 声明了静态资源目录：

registry.addResourceHandler("/swagger-ui/**") .addResourceLocations("classpath:/META-INF/resources/webjars/springfox-swagger-ui/");

SecurityConfig.java 放行匿名访问：

.requestMatchers("/swagger-ui.html", "/v3/api-docs/**", "/swagger-ui/**", "/druid/**").permitAll()

这几行缺任何一处，页面打开都会返回 401，是新手最常踩的坑。

第 4 步：给接口加上注解

做什么：控制器类上加分组名，每个接口方法上加描述。仓库里的 TestController.java 就是现成范例：

@Tag(name = "用户信息管理") @RestController @RequestMapping("/test/user") public class TestController extends BaseController { @Operation(summary = "获取用户列表") @GetMapping("/list") public R<List<UserEntity>> userList() { ... } }

实体字段用@Schema描述，例如文件末尾的UserEntity给每个字段都加了中文名，文档页的请求体结构里会直接显示。

注解速查 📌

历史上存在两套注解体系，一句话：旧的是 springfox，新的（本仓库）是 springdoc。

看到老教程里的@ApiOperation，直接换成@Operation就能用在当前仓库。

验证与排坑 🛠

验证三步走：

1. 启动RuoYiApplication，确认enabled: true开关已打开。
2. 浏览器访问http://localhost:8080/swagger-ui/index.html（也可输入/swagger-ui.html，会自动跳转到新页面）。
3. 登录系统拿到 token，点右上角Authorize填入，调用/test/user/list，应能返回用户列表数据。

常见坑：

• 页面空白或 404：springdoc.swagger-ui.enabled开关没打开；老 springfox 版本对应的是swagger.enabled=false。
• 打开页面报 401：SecurityConfig没放行 swagger 相关 URL，重点检查/v3/api-docs/**与/swagger-ui/**是否在放行列表里。
• 生产环境误开启：文档页会暴露全部接口结构，上线前记得把enabled改为false关闭。

收尾

一套完整的 RuoYi-Vue Swagger 配置就四件事：配置类、资源映射、Security 放行、接口注解，配完之后接口文档随代码自动生成。如果你在维护其他 Spring Boot 项目，这套做法可以直接搬过去用。下期聊聊 RuoYi-Vue 的 JWT token 机制：token 如何生成、校验与刷新。

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