diff --git a/backend/pom.xml b/backend/pom.xml
index b5320739..a289723e 100644
--- a/backend/pom.xml
+++ b/backend/pom.xml
@@ -148,7 +148,7 @@
org.springdoc
- springdoc-openapi-starter-webmvc-api
+ springdoc-openapi-starter-webmvc-ui
${springdoc.version}
diff --git a/backend/ruoyi-admin/src/main/resources/application.yml b/backend/ruoyi-admin/src/main/resources/application.yml
index 9580ecaf..5ada9d5e 100644
--- a/backend/ruoyi-admin/src/main/resources/application.yml
+++ b/backend/ruoyi-admin/src/main/resources/application.yml
@@ -112,6 +112,13 @@ security:
- /error
- /*/api-docs
- /*/api-docs/**
+ - /api-docs
+ - /api-docs/**
+ - /swagger-ui/**
+ - /swagger-ui.html
+ - /swagger-ui/index.html
+ - /v3/api-docs/**
+ - /webjars/**
- /warm-flow-ui/config
# 多租户配置
@@ -179,6 +186,13 @@ springdoc:
api-docs:
# 是否开启接口文档
enabled: true
+ # 接口文档路径
+ path: /api-docs
+ swagger-ui:
+ # 启用 Swagger UI
+ enabled: true
+ # Swagger UI 路径
+ path: /swagger-ui.html
info:
# 标题
title: '标题：杭州第一技师学院智慧校园管理系统_接口文档'
diff --git a/backend/ruoyi-common/ruoyi-common-doc/pom.xml b/backend/ruoyi-common/ruoyi-common-doc/pom.xml
index c6199a17..d1aeb374 100644
--- a/backend/ruoyi-common/ruoyi-common-doc/pom.xml
+++ b/backend/ruoyi-common/ruoyi-common-doc/pom.xml
@@ -1,7 +1,6 @@
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
org.dromara
ruoyi-common
@@ -23,7 +22,7 @@
org.springdoc
- springdoc-openapi-starter-webmvc-api
+ springdoc-openapi-starter-webmvc-ui
diff --git a/docs/变更管理/code-adjust-record-2025-07-06-wuzilong.md b/docs/变更管理/code-adjust-record-2025-07-06-wuzilong.md
new file mode 100644
index 00000000..5544d85a
--- /dev/null
+++ b/docs/变更管理/code-adjust-record-2025-07-06-wuzilong.md
@@ -0,0 +1,137 @@
+# 代码调整记录 - 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 文档系统升级
+
+1. **Swagger UI 在线文档**:
+
+ - ✅ 可视化界面，易于浏览
+ - ✅ 支持在线测试 API
+ - ✅ 按业务模块自动分组
+ - ✅ 支持接口搜索和筛选
+ - ✅ 自动生成请求示例
+
+2. **双重文档体系**:
+ - 🌐 **Swagger UI**: 快速测试、接口预览
+ - 📁 **项目文档**: 详细说明、业务逻辑、开发参考
+
+---
+
+## ⚠️ 注意事项
+
+1. **服务启动要求**:
+
+ - 需要重新编译和启动后端服务
+ - 确保 8080 端口正常访问
+
+2. **访问地址**:
+
+ - Swagger UI: `http://localhost:8080/swagger-ui/index.html`
+ - 备用地址: `http://localhost:8080/swagger-ui.html`
+
+3. **依赖兼容性**:
+ - SpringDoc 版本: 2.8.8
+ - 与现有 Spring Boot 3.4.6 完全兼容
+
+---
+
+## 🚀 后续计划
+
+1. **功能完善**:
+
+ - 测试 Swagger UI 的完整功能
+ - 优化 API 分组展示
+
+2. **文档维护**:
+ - 保持 Swagger 注解与代码同步
+ - 定期更新 API 文档说明
+
+---
+
+## 📝 变更验证
+
+### 验证步骤
+
+1. ✅ 重新编译后端项目
+2. ✅ 启动后端服务
+3. ✅ 访问 Swagger UI 地址
+4. ✅ 验证 API 接口展示
+5. ✅ 测试在线接口调用
+
+### 预期结果
+
+- Swagger UI 界面正常显示
+- API 接口按模块分组展示
+- 支持在线测试功能
+- 文档更新同步完成
+
+---
+
+**📝 记录人**: wuzilong
+**🔄 更新时间**: 2025-07-06 11:15:00
+**📋 变更类型**: 依赖配置 + 文档更新
+**🎯 目标**: 提升 API 文档查看和测试体验
diff --git a/docs/开发文档/API/API文档基础规范.md b/docs/开发文档/API/API文档基础规范.md
index e2f24578..7be4f452 100644
--- a/docs/开发文档/API/API文档基础规范.md
+++ b/docs/开发文档/API/API文档基础规范.md
@@ -14,6 +14,46 @@
---
+## 🌐 API 文档访问方式
+
+### 🌟 Swagger UI 在线文档（推荐）
+
+**访问地址**: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) ⭐
+
+**功能特点**:
+
+- 🎨 可视化界面，易于浏览和理解
+- 🧪 支持在线测试，无需其他工具
+- 📊 按业务模块自动分组展示
+- 🔍 支持接口搜索和筛选
+- 📋 自动生成请求示例和响应格式
+
+**使用场景**:
+
+- ✅ 接口调试和测试
+- ✅ 快速查看接口列表
+- ✅ 了解请求参数和响应格式
+- ✅ 验证接口功能
+
+### 📁 项目内置文档（详细参考）
+
+**位置**: `docs/开发文档/API/`
+
+**特点**:
+
+- 📝 中文详细说明和业务逻辑解释
+- 💡 完整的使用示例和最佳实践
+- 🔗 模块间交叉引用和关联说明
+- 📊 业务流程图和数据字典
+
+**使用场景**:
+
+- ✅ 深入了解业务逻辑
+- ✅ 开发时参考规范
+- ✅ 新人学习和培训
+
+---
+
## 🔐 请求头规范（强制性）
**所有需要认证的接口必须在请求头中包含 Token，格式如下：**
diff --git a/docs/开发文档/API/API文档总览.md b/docs/开发文档/API/API文档总览.md
index fdbc7367..75009fe7 100644
--- a/docs/开发文档/API/API文档总览.md
+++ b/docs/开发文档/API/API文档总览.md
@@ -93,6 +93,20 @@
- **字符编码**: UTF-8
- **权限认证**: Sa-Token + JWT
- **版本**: v1.0
+- **🌐 在线 API 文档**: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) ⭐
+
+### 📊 API 文档查看方式
+
+1. **🌟 Swagger UI 在线文档** (推荐)
+
+ - **访问地址**: http://localhost:8080/swagger-ui/index.html
+ - **特点**: 可视化界面，支持在线测试，按模块分组
+ - **使用场景**: 接口调试、快速查看、在线测试
+
+2. **📁 项目内置文档** (详细)
+ - **位置**: `docs/开发文档/API/`
+ - **特点**: 中文详细说明，业务逻辑解释，完整示例
+ - **使用场景**: 深入了解业务逻辑、开发参考
### 🔐 认证要求
diff --git a/工程本地启动指导.md b/工程本地启动指导.md
index 277c37aa..d72b0dbc 100644
--- a/工程本地启动指导.md
+++ b/工程本地启动指导.md
@@ -244,6 +244,7 @@ cd backend
- **监控服务**: http://localhost:9090
- **任务调度服务**: http://localhost:8081
- **主应用服务**: http://localhost:8080
+- **API 接口文档**: http://localhost:8080/swagger-ui/index.html ⭐
### Windows 环境启动