# Knife4j 成功配置说明

`http://localhost:8080/doc.html`

## 📋 查看所有模块分组

### 方法1：使用分组下拉框

在Knife4j界面的**左上角**，有一个下拉框，点击它可以切换不同的模块分组：

1. 全部接口
2. 生产模块
3. 销售模块
4. 仓库模块
5. 主数据模块
6. 设备模块
7. 质量模块
8. 系统模块

**位置**：页面左上角，"YJH-MES 制造执行系统 API文档" 标题下方

### 方法2：直接访问分组API文档

你也可以直接访问特定分组的API文档：

```
http://localhost:8080/v3/api-docs?group=全部接口
http://localhost:8080/v3/api-docs?group=生产模块
http://localhost:8080/v3/api-docs?group=销售模块
http://localhost:8080/v3/api-docs?group=仓库模块
http://localhost:8080/v3/api-docs?group=主数据模块
http://localhost:8080/v3/api-docs?group=设备模块
http://localhost:8080/v3/api-docs?group=质量模块
http://localhost:8080/v3/api-docs?group=系统模块
```

## 🎯 如何使用Knife4j

### 1. 切换模块分组

- 点击左上角的下拉框
- 选择你想查看的模块（如"生产模块"）
- 左侧会显示该模块的所有接口

### 2. 查看接口详情

- 在左侧接口列表中点击接口
- 右侧会显示接口的详细信息：
  - 接口路径
  - 请求方法（GET/POST/PUT/DELETE）
  - 请求参数
  - 响应示例

### 3. 测试接口

#### 步骤1：获取Token

1. 切换到"系统模块"或"全部接口"
2. 找到 `POST /login` 接口
3. 点击接口，切换到"调试"标签
4. 在请求参数中输入：
   ```json
   {
     "username": "admin",
     "password": "admin123"
   }
   ```
5. 点击"发送"按钮
6. 在响应中找到 `token` 字段，复制token值

#### 步骤2：设置全局Token

1. 点击页面右上角的"文档管理"按钮（齿轮图标）
2. 选择"全局参数设置"
3. 点击"添加参数"按钮
4. 填写参数信息：
   - **参数名称**：`Authorization`
   - **参数值**：粘贴刚才复制的token
   - **参数类型**：选择 `header`
   - **参数位置**：选择 `header`
5. 点击"确定"保存

现在所有接口都会自动带上这个token！

#### 步骤3：测试其他接口

1. 切换到你想测试的模块（如"生产模块"）
2. 选择一个接口（如批量自动完成接口）
3. 点击接口，切换到"调试"标签
4. 填写必要的参数
5. 点击"发送"按钮
6. 查看响应结果

### 4. 批量自动完成接口测试示例

1. 切换到"生产模块"
2. 找到 `POST /production/autoComplete/batchAutoComplete` 接口
3. 切换到"调试"标签
4. 在请求体中输入：
   ```json
   {
     "orderNumbers": ["XS20260306002"],
     "plan": {
       "isGeneratePlan": 1,
       "assignedUserIds": "1,2,3"
     },
     "workOrder": {
       "isGenerateWorkOrder": 1,
       "routeId": 1,
       "processStartTime": "2026-03-06 12:00:00"
     },
     "reportWorkOrder": {
       "isGenerateReportWorkOrder": 0,
       "reporters": []
     }
   }
   ```
5. 点击"发送"
6. 查看响应结果

## 🎨 Knife4j特色功能

### 1. 搜索接口

- 点击右上角的搜索图标（🔍）
- 输入接口路径或描述
- 快速定位到目标接口

### 2. 离线文档

- 点击右上角"离线文档"按钮
- 选择格式：
  - Markdown：适合文档编辑
  - HTML：可以直接在浏览器打开
- 点击"下载"

### 3. 主题切换

- 点击右上角的主题切换按钮
- 选择你喜欢的主题：
  - 默认主题（蓝色）
  - 暗黑主题（黑色）
  - 简约主题（白色）

### 4. 接口排序

- 在左侧接口列表上方有排序按钮
- 可以按：
  - 默认排序
  - 字母排序
  - 标签排序

## 📊 界面说明

```
┌─────────────────────────────────────────────────────────┐
│  [分组下拉框▼]  YJH-MES API文档    [搜索🔍] [主题] [文档管理⚙️] │
├──────────────┬──────────────────────────────────────────┤
│              │                                          │
│  接口列表    │         接口详情 / 调试区域              │
│              │                                          │
│  📁 Controller1 │  接口路径: POST /api/xxx              │
│    └─ 接口1  │  请求参数: [...]                        │
│    └─ 接口2  │  响应示例: [...]                        │
│              │                                          │
│  📁 Controller2 │  [调试] [文档] 标签                   │
│    └─ 接口3  │                                          │
│              │                                          │
└──────────────┴──────────────────────────────────────────┘
```

## 🔧 如果看不到其他模块

### 检查1：确认分组下拉框位置

分组下拉框在页面**左上角**，标题"YJH-MES 制造执行系统 API文档"的**下方**。

### 检查2：刷新页面

按 `Ctrl+F5` 强制刷新页面，清除缓存。

### 检查3：查看浏览器控制台

1. 按 `F12` 打开开发者工具
2. 切换到 `Console` 标签
3. 查看是否有错误信息

### 检查4：验证分组是否存在

访问以下地址，查看是否返回JSON数据：

```
http://localhost:8080/v3/api-docs?group=生产模块
```

如果返回JSON数据，说明分组配置正确。

## 📝 导出API文档

### 导出为Markdown

1. 点击右上角"离线文档"
2. 选择"Markdown"
3. 点击"下载"
4. 得到 `.md` 文件

### 导出为HTML

1. 点击右上角"离线文档"
2. 选择"HTML"
3. 点击"下载"
4. 得到 `.html` 文件，可以直接在浏览器打开

### 导出为OpenAPI JSON

访问：
```
http://localhost:8080/v3/api-docs
```

复制JSON内容，可以导入到：
- Postman
- Apifox
- Insomnia
- 其他支持OpenAPI 3.0的工具

## 🎉 成功标志

你已经成功配置了Knife4j，现在可以：

- ✅ 访问 `http://localhost:8080/doc.html`
- ✅ 看到美观的Knife4j界面
- ✅ 切换不同的模块分组
- ✅ 查看接口详情
- ✅ 测试接口
- ✅ 设置全局Token
- ✅ 导出离线文档

## 📚 相关文档

- **Knife4j使用指南**：`.tasks/2026-03-06_Knife4j使用指南.md`
- **批量自动完成接口文档**：`.tasks/2026-02-27_v2.0.002_ATS接口文档.md`

## 💡 小贴士

1. **全局Token设置**：设置一次，所有接口都会自动带上
2. **搜索功能**：快速定位接口，支持模糊搜索
3. **离线文档**：可以导出给团队成员查看
4. **主题切换**：根据个人喜好选择主题
5. **响应示例**：每个接口都有详细的响应示例

---

**恭喜你成功配置了API文档系统！** 🎉

**更新时间**：2026-03-02