RuoYi-Vue Swagger3.0 配置实战5 个配置点搭出 OpenAPI 3.0 接口文档【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBootSpring SecurityJWTVue Element 的前后端分离权限管理系统同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue前后端联调到第二天后端甩来一串 curl前端盯着抓包逐字段对参数。RuoYi-Vue Swagger3.0 配置干的就是省掉这种扯皮的事按 OpenAPI 3.0 接口文档规范自动生成一份能直接点 Try it out 的页面接口改签名文档跟着变。下面按当年踩坑的顺序把从引依赖到页面跑通的 5 个配置点逐个拆开每一节都对应一个当时真实卡住的报错。1. 依赖先挂上一个坐标带出整套文档能力这一步在 pom 里加一个坐标就行但它是后面所有配置的地基dependency groupIdio.springfox/groupId artifactIdspringfox-boot-starter/artifactId version3.0.0/version /dependencyspringfox-boot-starter 会连带把 Docket 模型类和 swagger-ui 的静态资源一起打包进来第四节映射的就是这批 webjars。版本建议钉在 3.0.0这是和 Spring Boot 2.x 组合验证得最多的版本再往上的 springdoc 是另一套 API配置类得整个重写两者别混用。2. 建 Docket让文档按 OpenAPI 3.0 规范生成SwaggerConfig.java 放在 ruoyi-admin 的 web/core/config 包下是整套文档配置的中枢。它先从配置文件里读两个开关/** 是否开启swagger */ Value(${swagger.enabled}) private boolean enabled; /** 设置请求的统一前缀 */ Value(${swagger.pathMapping}) private String pathMapping;这两个字段配合 yml 里的同名 key让文档在不同环境能一键启停。生产环境把 swagger.enabled 关掉api-docs 接口就不再生成等于给自己留了个安全出口。真正的中枢是这个 Bean一句话概括告诉 springfox 按哪套规范、扫哪些接口、挂什么安全方案。Bean public Docket createRestApi() { return new Docket(DocumentationType.OAS_30) .enable(enabled) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class)) .paths(PathSelectors.any()) .build() .securitySchemes(securitySchemes()) .securityContexts(securityContexts()) .pathMapping(pathMapping); }DocumentationType.OAS_30 决定产物是 OpenAPI 3.0 而不是老的 Swagger 2.0 格式UI 用哪套渲染器全靠它。withMethodAnnotation 把扫描范围收窄到打过注解的方法没标注解的 Controller 不会混进文档联调时看到的东西更聚焦。pathMapping 填错的后果是不报错UI 拉不到接口定义页面打开一片空白这是仅次于 403 的第二大坑。3. 挂上文档头牌把 Token 认证配到位apiInfo首页那块牌写什么private ApiInfo apiInfo() { return new ApiInfoBuilder() .title(标题若依管理系统_接口文档) .description(描述用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...) .contact(new Contact(ruoyiConfig.getName(), null, null)) .version(版本号: ruoyiConfig.getVersion()) .build(); }这段决定文档首页展示的内容标题、用途说明、联系人和版本号。版本号直接拼 ruoyiConfig.getVersion()系统升版本文档跟着变省掉一处手工同步。description 建议写上模块清单接手的同学扫一眼就知道文档覆盖了什么、接口该找谁要。配好 springfox securityContextsSwagger 安全认证 Token 挂上去这三段是 Token 认证的标准挂法securitySchemes 定义一种 API Key 方案头名就叫 Authorization正好对上 RuoYi 的 JWT 请求头securityContexts 声明它对哪些接口生效operationSelector 里的 /.* 表示全部接口。private ListSecurityScheme securitySchemes() { ListSecurityScheme apiKeyList new ArrayList(); apiKeyList.add(new ApiKey(Authorization, Authorization, In.HEADER.toValue())); return apiKeyList; } private ListSecurityContext securityContexts() { ListSecurityContext securityContexts new ArrayList(); securityContexts.add( SecurityContext.builder() .securityReferences(defaultAuth()) .operationSelector(o - o.requestMappingPattern().matches(/.*)) .build()); return securityContexts; } private ListSecurityReference defaultAuth() { AuthorizationScope authorizationScope new AuthorizationScope(global, accessEverything); AuthorizationScope[] authorizationScopes new AuthorizationScope[1]; authorizationScopes[0] authorizationScope; ListSecurityReference securityReferences new ArrayList(); securityReferences.add(new SecurityReference(Authorization, authorizationScopes)); return securityReferences; }只配 schemes 不配 contexts 是最常见的漏法Authorize 按钮有了却挂不到具体接口上Try it out 发出去的请求不带 token后端直接 401。springfox securityContexts 配置看起来啰嗦省掉哪一行都会在最需要它的联调现场暴雷。4. 让页面真正能打开资源映射 安全放行静态资源映射swagger-ui 的文件从哪来ResourcesConfig.java 平时负责本地上传文件的路径映射这次多出来的这段是给文档页开的资源口子registry.addResourceHandler(/swagger-ui/**) .addResourceLocations(classpath:/META-INF/resources/webjars/springfox-swagger-ui/);swagger-ui 的 html 和 js 都躺在 jar 包深处的 webjars 目录里Spring MVC 默认不会把它们映射到 URL 上。不加这行地址栏敲 /swagger-ui/index.html 就是 404。而且 404 和 403 在排查顺序上经常被搞反先想到 403 的人多半没检查资源映射。放行 Swagger 相关的 5 条 URLSecurityConfig.java 里 Spring Security 默认拦截一切请求文档链路也不例外需要显式开匿名口子http.authorizeRequests() .antMatchers(/swagger-ui.html, /swagger-resources/**, /webjars/**, /*/api-docs, /druid/**).permitAll()⚠️ 这里不配的话浏览器打开文档页直接 403响应体里没有有效信息排查时很容易先怀疑到资源映射头上。5 条 matcher 各管一摊/swagger-ui.html 是页面入口/swagger-resources/** 和 /*/api-docs 是 UI 运行时拉接口定义的 JSON/webjars/** 承载前端静态文件。缺任何一条页面都会在加载到一半时静默断掉。5. 注解怎么写拿 TestController 当示范TestController.java 是仓库里专门留给联调试刀的接口三个注解的用法一目了然RestController RequestMapping(/test/swagger) Api(value Swagger测试接口, tags {Swagger测试接口}) public class TestController { ApiOperation(获取列表) GetMapping(/list) public AjaxResult list() { ListString list new ArrayList(); list.add(swagger); list.add(test); return AjaxResult.success(list); } 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); } }Api 描述类ApiOperation 描述方法ApiImplicitParam 补参数说明分工明确。前面 Docket 只扫带 ApiOperation 的方法所以这套注解同时决定了接口进不进文档、进文档后长什么样。这也解释了为什么 Demo 要单独开一个 Controller没标注解的存量接口自动隐身不用挨个清理。6. 启动验证四步确认全链路启动 RuoYiApplication等端口监听就绪后浏览器打开 http://localhost:8080/swagger-ui/index.html。对着下面四样逐条核对全过才算配完页面标题显示若依管理系统_接口文档版本号对得上说明 apiInfo 生效左侧分组能看到Swagger测试接口说明 Docket 扫描生效每个接口行旁有 Authorize 按钮点开能填 Authorization说明安全方案生效把登录接口返回的 token 粘进去Try it out 调 /test/swagger/list 返回 200说明 Token 认证打通✅ 缺哪一条就回头查对应那一节。四样齐活之后这套文档就跟着代码走了接口改签名、加参数重启即更新再不用人肉维护接口说明。下一步可以聊聊把 api-docs 导出成 YAML 丢进 CI前端拉一份静态文件就能离线查联调环境也不用再依赖后端开着文档开关。【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBootSpring SecurityJWTVue Element 的前后端分离权限管理系统同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
