RuoYi-Vue 接口文档 5 分钟跑通：Swagger 3.0 配置全解

RuoYi-Vue 接口文档 5 分钟跑通：Swagger 3.0 配置全解

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

前端同学第一天联调，翻遍项目只找到一个登录页，接口到底长什么样全靠自己猜。RuoYi-Vue 后端其实已经内置了 Swagger 接口文档，这篇按你查看的先后顺序，把依赖、扫描范围、认证配置和放行规则这条链路一次讲透。

前置准备：先认清 4 个关键位置

• 环境：Java 17，Spring Boot 4.1.0
• 依赖：springdoc-openapi-starter-webmvc-ui3.1.0（springdoc——OpenAPI 3.0 的 Spring Boot 实现，负责扫描接口并生成文档）
• 文档总配置：application.yml
• 文档认证配置：SwaggerConfig.java
• 安全放行规则：SecurityConfig.java

第 1 步：确认 springdoc 依赖已就位

依赖声明在启动模块 ruoyi-admin/pom.xml 里，版本由父工程统一管理：

<!-- spring-doc --> <dependency> <groupId>org.springdoc</groupId> <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId> </dependency>

这个 artifact 同时干两件事：生成接口元数据，并提供/swagger-ui这套静态 UI 页面。它只挂在ruoyi-admin启动模块上，所以文档能力只在完整应用里生效，单独跑业务模块看不到。

第 2 步：看懂扫描范围，为什么默认只有测试接口

打开 application.yml，找到springdoc节点：

springdoc: api-docs: path: /v3/api-docs swagger-ui: enabled: true path: /swagger-ui.html tags-sorter: alpha group-configs: - group: 'default' display-name: '测试模块' paths-to-match: '/**' packages-to-scan: com.ruoyi.web.controller.tool

两个要点：

• packages-to-scan限定了只扫描com.ruoyi.web.controller.tool包——这就是你打开文档只看到测试接口、看不到业务接口的直接原因。
• enabled: true是 UI 的总开关；path决定 UI 入口，/v3/api-docs则是元数据地址。

第 3 步：给文档挂上 Token 认证按钮

RuoYi 用 JWT 做鉴权，文档页右上角的 Authorize 按钮就是用来填 token 的。这套行为由 SwaggerConfig.java 里的两个 Bean 决定：

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

SecurityScheme相当于文档的"锁说明"：声明密钥放在Authorization请求头、格式是Bearer前缀。同类的customOpenApi()里还有getApiInfo()，就是文档首页那张名片——标题、版本和联系人，联系人取自ruoyi.name、版本取自ruoyi.version，改配置即可换内容。

第 4 步：放行文档地址，别让 Security 把它拦下来

项目启用了 Spring Security，默认所有请求都要鉴权，文档页也不例外。SecurityConfig.java 里有一行专门放行：

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

这一行让 UI 页面和元数据接口匿名可访问，是文档能不能打开的前提。没有它，页面和/v3/api-docs都会直接 401。

第 5 步：给接口加注解，让文档"有内容可写"

👇 打开示例 TestController.java，看两处注解就够了：

@Tag(name = "用户信息管理") @Operation(summary = "获取用户列表")

• @Tag决定接口在文档里归到哪个分组，@Operation决定方法那一行显示什么名字。
• 参数和返回值结构则由实体上的@Schema描述，例如UserEntity的四个字段都会自动出现在参数表里。

方法没加@Operation，文档里就没有这一行——注解就是文档内容的来源。

验证与排错：启动后应该看到什么

启动RuoYiApplication，浏览器访问http://localhost:8080/swagger-ui/index.html：

• 页面左侧应按tags-sorter排序列出"用户信息管理"分组，展开后能看到五个接口和UserEntity结构。
• 点右上角 Authorize，粘贴登录接口返回的 token，再 Try it out，应正常返回R结构的结果。

高频问题速查：

• 文档页直接 401：放行规则没生效，确认第四步的permitAll里包含你要访问的路径。
• UI 打不开：检查springdoc.swagger-ui.enabled是否为true，以及path与你实际访问的地址是否一致。
• 接口不显示：确认 Controller 所在包在packages-to-scan范围内，且方法加了@Operation。

速查：关键配置键一览

想让全部业务接口进文档，可以把packages-to-scan指向com.ruoyi.web.controller；按模块拆多份文档，则往group-configs里再加一组即可。

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