3.1 KiB
3.1 KiB
代码调整记录 - 2025-07-06 - wuzilong
📋 变更概述
变更目标: 为项目添加 Swagger UI 支持并更新相关文档
变更时间: 2025-07-06 11:15:00
变更类型: 依赖配置优化 + 文档更新
影响范围: 后端依赖、API 文档系统
🔧 技术变更
1. Maven 依赖配置更新
文件: backend/pom.xml
变更内容:
- 替换
springdoc-openapi-starter-webmvc-api为springdoc-openapi-starter-webmvc-ui - 增加 Swagger UI 界面支持
文件: backend/ruoyi-common/ruoyi-common-doc/pom.xml
变更内容:
- 同步更新 SpringDoc 依赖配置
2. 安全配置优化
文件: backend/ruoyi-admin/src/main/resources/application.yml
变更内容:
- 在 security.excludes 中添加 Swagger UI 相关路径
- 启用 SpringDoc Swagger UI 配置
📚 文档更新
1. 工程启动指导文档
文件: 工程本地启动指导.md
变更内容:
- 在"启动验证"部分添加 API 接口文档访问地址
- 新增：
http://localhost:8080/swagger-ui/index.html ⭐
2. API 文档总览
文件: docs/开发文档/API/API文档总览.md
变更内容:
- 在基础配置中添加在线 API 文档链接
- 新增"API 文档查看方式"章节，说明 Swagger UI 和项目文档的不同特点
3. API 基础规范文档
文件: docs/开发文档/API/API文档基础规范.md
变更内容:
- 新增"API 文档访问方式"章节
- 详细说明 Swagger UI 在线文档的功能特点和使用场景
- 对比说明在线文档与项目内置文档的适用场景
🎯 功能提升
API 文档系统升级
-
Swagger UI 在线文档:
- ✅ 可视化界面，易于浏览
- ✅ 支持在线测试 API
- ✅ 按业务模块自动分组
- ✅ 支持接口搜索和筛选
- ✅ 自动生成请求示例
-
双重文档体系:
- 🌐 Swagger UI: 快速测试、接口预览
- 📁 项目文档: 详细说明、业务逻辑、开发参考
⚠️ 注意事项
-
服务启动要求:
- 需要重新编译和启动后端服务
- 确保 8080 端口正常访问
-
访问地址:
- Swagger UI:
http://localhost:8080/swagger-ui/index.html - 备用地址:
http://localhost:8080/swagger-ui.html
- Swagger UI:
-
依赖兼容性:
- SpringDoc 版本: 2.8.8
- 与现有 Spring Boot 3.4.6 完全兼容
🚀 后续计划
-
功能完善:
- 测试 Swagger UI 的完整功能
- 优化 API 分组展示
-
文档维护:
- 保持 Swagger 注解与代码同步
- 定期更新 API 文档说明
📝 变更验证
验证步骤
- ✅ 重新编译后端项目
- ✅ 启动后端服务
- ✅ 访问 Swagger UI 地址
- ✅ 验证 API 接口展示
- ✅ 测试在线接口调用
预期结果
- Swagger UI 界面正常显示
- API 接口按模块分组展示
- 支持在线测试功能
- 文档更新同步完成
📝 记录人: wuzilong
🔄 更新时间: 2025-07-06 11:15:00
📋 变更类型: 依赖配置 + 文档更新
🎯 目标: 提升 API 文档查看和测试体验