8.0 KiB
8.0 KiB
API 文档总览
📋 文档说明
本文档是校园管理系统 API 接口的总览和导航页面。为了提高文档的可维护性和可读性，API 文档已按业务模块进行拆分。
拆分完成时间: 2025-07-01
拆分目的: 按业务模块管理，便于维护和查找，减少单个文件过大的问题
📊 API 文档架构
🔗 分模块 API 文档
| 文档名称 | 文件路径 | 主要内容 | 适用场景 |
|---|---|---|---|
| 📋 API 文档基础规范 | API 文档基础规范.md | 请求头规范、响应格式、状态码、错误码、数据字典 | 所有开发人员必读 |
| 🔐 用户认证登录 API | 用户认证登录 API.md | 用户登录、退出、验证码、用户信息、租户管理 | 认证相关开发 |
| 🛠️ 物业报修管理 API | 物业报修管理 API.md | 维修分类、报修工单、进度跟踪、服务评价 | 物业报修功能开发 |
| 📊 后勤满意度调查 API | 后勤满意度调查 API.md | 问卷管理、答题、题目管理、答题记录 | 满意度调查功能开发 |
| 🏢 场地预约管理 API | 场地预约管理 API.md | 场地信息管理、预约申请、审批流程、冲突检查 | 场地预约功能开发 |
| 🎭 报告厅预约审核 API | 报告厅预约审核 API.md | 审核建议生成、时间冲突检查、批量审核处理 | 报告厅审核功能开发 |
📝 阅读建议
- 首次阅读: 先阅读 API 文档基础规范.md 了解通用规范
- 业务开发: 根据开发的功能模块选择对应的 API 文档
- 交叉引用: 各模块文档间有交叉引用，便于快速查找相关接口
🎯 快速导航
🔍 按功能查找接口
🔐 用户认证相关
🛠️ 物业报修相关
📊 满意度调查相关
🏢 场地预约相关
🎭 报告厅审核相关
🔍 按开发阶段查找
🚀 项目初期
- API 文档基础规范.md - 了解通用规范
- 用户认证登录 API.md - 实现用户认证
- 选择业务模块文档进行开发
🛠️ 功能开发
- 根据具体功能模块查找对应 API 文档
- 参考接口示例和错误码说明
- 使用数据字典了解枚举值含义
🧪 接口测试
- 参考各文档中的请求示例
- 使用提供的测试脚本
- 查看错误码说明进行问题排查
📋 通用信息
🔧 基础配置
- 基础路径:
/api - 响应格式: JSON
- 字符编码: UTF-8
- 权限认证: Sa-Token + JWT
- 版本: v1.0
- 🌐 在线 API 文档: http://localhost:8080/swagger-ui/index.html ⭐
📊 API 文档查看方式
-
🌟 Swagger UI 在线文档 (推荐)
- 访问地址: http://localhost:8080/swagger-ui/index.html
- 特点: 可视化界面，支持在线测试，按模块分组
- 使用场景: 接口调试、快速查看、在线测试
-
📁 项目内置文档 (详细)
- 位置:
docs/开发文档/API/ - 特点: 中文详细说明，业务逻辑解释，完整示例
- 使用场景: 深入了解业务逻辑、开发参考
- 位置:
🔐 认证要求
所有需要认证的接口都必须在请求头中携带：
{
"Authorization": "Bearer {access_token}",
"clientid": "e5cd7e4891bf95d1d19206ce24a7b32e",
"Content-Type": "application/json;charset=utf-8"
}
详细说明请参考：API 文档基础规范.md
📊 响应格式
- 分页列表: TableDataInfo 格式 (total, rows, code, msg)
- 非分页接口: R 类型格式 (code, msg, data)
- 错误响应: 统一错误格式
详细说明请参考：API 文档基础规范.md
🔄 文档维护
📝 更新规则
- 基础规范变更: 更新 API 文档基础规范.md
- 认证相关变更: 更新 用户认证登录 API.md
- 物业报修变更: 更新 物业报修管理 API.md
- 满意度调查变更: 更新 后勤满意度调查 API.md
- 总览更新: 根据需要更新本文档
🚨 强制要求
- 同步更新: 代码变更时必须同步更新对应的 API 文档
- 向下兼容: 新版本 API 必须考虑向下兼容性
- 版本记录: 重大变更需要在相应文档中记录版本信息
📞 联系方式
如有 API 文档相关问题，请联系开发团队或查看项目仓库的 Issues。
📈 版本历史
v2.0.0 (2025-07-01) - API 文档拆分重构
- 🔄 重大架构调整: API 文档按业务模块拆分
- 📋 新增基础规范文档: 统一管理通用规范
- 🔐 独立认证 API 文档: 用户认证登录专门文档
- 🛠️ 物业报修 API 文档: 报修管理专门文档
- 📊 满意度调查 API 文档: 问卷答题专门文档
- 📝 中文文件命名: 便于快速识别和查找
- 🔗 交叉引用系统: 各文档间建立引用关系
- 📚 总览导航: 提供统一的文档入口
v1.x.x (2025-01-26 及之前)
参考各个拆分文档中的版本历史记录。
📝 维护: API 文档总览和导航
🔄 更新: 2025-07-01
📁 架构: 4 个专门 API 文档 + 1 个总览文档
🎯 目标: 提供清晰的 API 文档导航和管理体系