企业官网建设流程全解析

RuoYi框架深度定制Swagger UI：打造企业级API文档门户

在当今前后端分离的开发模式下，API文档的质量直接影响着团队协作效率。RuoYi作为国内流行的快速开发框架，默认集成了Swagger用于接口文档生成，但其原生UI在美观度和功能性上往往难以满足企业级需求。本文将带你从零实现一套基于swagger-bootstrap-ui的深度定制方案，涵盖主题切换、权限集成、多环境适配等实战技巧，助你打造专业级的API文档中心。

1. 为什么需要定制Swagger UI？

原生Swagger UI虽然功能完整，但在实际企业应用中存在几个明显痛点：

• 视觉风格单一：默认蓝白配色缺乏品牌识别度
• 功能扩展有限：缺少接口排序、搜索高亮等实用功能
• 权限控制缺失：无法与现有权限系统集成
• 移动端适配差：响应式布局效果不理想

swagger-bootstrap-ui作为国内开发者维护的增强方案，提供了以下核心优势：

2. 环境配置与基础集成

2.1 依赖引入与版本选择

在ruoyi-admin模块的pom.xml中添加依赖（建议使用最新稳定版）：

<dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>

注意：版本选择需与Spring Boot版本兼容，Spring Boot 2.3+推荐使用1.9.6+

2.2 访问路径改造

全局搜索替换Swagger默认访问路径：

1. 修改swagger-resources配置位置：

@Configuration @EnableSwagger2 public class SwaggerConfig { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .pathMapping("/doc.html") // 关键修改 // ...其他配置 } }

2. 更新安全配置（在SecurityConfig中）：

@Override protected void configure(HttpSecurity http) throws Exception { http.authorizeRequests() .antMatchers("/doc.html").permitAll() // 放行新路径 .antMatchers("/webjars/**").permitAll() // ...其他配置 }

3. 深度定制实战技巧

3.1 多主题切换方案

在application.yml中添加皮肤配置：

swagger: bootstrap-ui: theme: - dark # 暗黑主题 - feeling # 清新蓝 - material # 材质设计

通过URL参数动态切换主题：

http://localhost:8080/doc.html?theme=dark

3.2 与RuoYi权限系统集成

实现API文档的权限控制：

@Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .securitySchemes(Collections.singletonList( new ApiKey("Authorization", "Authorization", "header"))) .enable(hasPermission("system:swagger:view")) // 结合权限注解 // ...其他配置 }

3.3 接口分组优化

按业务模块划分文档分组：

@Bean public Docket userApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("用户中心") .select() .apis(RequestHandlerSelectors.basePackage("com.ruoyi.web.controller.system")) .build(); } @Bean public Docket orderApi() { return new Docket(DocumentationType.SWAGGER_2) .groupName("订单管理") .select() .apis(RequestHandlerSelectors.basePackage("com.ruoyi.web.controller.order")) .build(); }

4. 高级功能扩展

4.1 离线文档生成

通过增强注解生成Markdown文档：

@ApiOperationSupport( order = 1, author = "张三", responses = @ApiResponse(code = 200, message = "成功") ) @ApiOperation(value = "创建用户", notes = "需要管理员权限") @PostMapping("/users") public AjaxResult createUser(...) { // 方法实现 }

生成命令：

java -jar swagger-bootstrap-ui.jar --markdown --output api-docs.md

4.2 接口Mock配置

为未实现的接口配置Mock数据：

@ApiOperation(value = "获取用户列表", mock = @Mock(value = """ { "code": 200, "data": [ {"id": 1, "name": "测试用户"} ] } """)) @GetMapping("/users") public AjaxResult getUsers() { // 待实现 }

4.3 多环境适配策略

根据不同环境调整文档配置：

@Profile({"dev", "test"}) // 仅开发测试环境开启 @Configuration @EnableSwagger2 public class SwaggerConfig { // 配置内容 }

在application-prod.yml中关闭文档：

swagger: enabled: false

5. 性能优化与安全加固

5.1 资源加载优化

配置CDN加速静态资源：

@Bean public UiConfiguration uiConfig() { return UiConfigurationBuilder.builder() .validatorUrl("") // 禁用验证器 .supportedSubmitMethods(UiConfiguration.Constants.NO_SUBMIT_METHODS) .build(); }

5.2 敏感信息过滤

过滤不需要展示的接口：

@Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .select() .apis(Predicates.not( RequestHandlerSelectors.withMethodAnnotation(ApiIgnore.class) )) .build() .ignoredParameterTypes(Authentication.class); // 过滤认证参数 }

5.3 请求参数加密

处理敏感参数展示：

@ApiModelProperty(value = "密码", accessMode = AccessMode.READ_ONLY) private String password;

实际项目中我们发现，通过合理配置swagger-bootstrap-ui，API文档的可用性提升明显。特别是在对接移动端团队时，分组功能和Mock数据能减少60%以上的沟通成本。建议将文档皮肤与企业VI系统保持一致，可以进一步提升技术品牌形象。