RuoYi-Vue Swagger3.0 接口文档配置指南4 步生成专业 API 文档【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBootSpring SecurityJWTVue Element 的前后端分离权限管理系统同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue先看效果 ✨配置完成后启动 RuoYi-Vue 项目打开http://localhost:8080/swagger-ui/index.html接口文档就在页面上自动生成接口按模块分组、请求参数、返回结构一目了然每个接口还带 Try it out 按钮可以直接在线调试。前端不用再追着要参数说明后端也不用手写接口文档文档从代码里长出来永远不会过期。为什么值得配手写接口文档最大的问题是跟不上代码接口一改文档就旧前端拿到的永远是过期版本。接入 Swagger3.0OpenAPI 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.toolenabled决定页面是否可用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 认证单独一个 BeanBean 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 RListUserEntity userList() { ... } }实体字段用Schema描述例如文件末尾的UserEntity给每个字段都加了中文名文档页的请求体结构里会直接显示。注解速查 历史上存在两套注解体系一句话旧的是 springfox新的本仓库是 springdoc。用途springfoxSwagger2 时代springdoc本仓库OAS3类上分组描述ApiTag方法上接口描述ApiOperationOperation参数描述ApiImplicitParam / ApiParamParameter / Schema实体字段描述ApiModelPropertySchema看到老教程里的ApiOperation直接换成Operation就能用在当前仓库。验证与排坑 验证三步走启动RuoYiApplication确认enabled: true开关已打开。浏览器访问http://localhost:8080/swagger-ui/index.html也可输入/swagger-ui.html会自动跳转到新页面。登录系统拿到 token点右上角Authorize填入调用/test/user/list应能返回用户列表数据。常见坑页面空白或 404springdoc.swagger-ui.enabled开关没打开老 springfox 版本对应的是swagger.enabledfalse。打开页面报 401SecurityConfig没放行 swagger 相关 URL重点检查/v3/api-docs/**与/swagger-ui/**是否在放行列表里。生产环境误开启文档页会暴露全部接口结构上线前记得把enabled改为false关闭。收尾一套完整的 RuoYi-Vue Swagger 配置就四件事配置类、资源映射、Security 放行、接口注解配完之后接口文档随代码自动生成。如果你在维护其他 Spring Boot 项目这套做法可以直接搬过去用。下期聊聊 RuoYi-Vue 的 JWT token 机制token 如何生成、校验与刷新。【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBootSpring SecurityJWTVue Element 的前后端分离权限管理系统同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考