257 lines
6.8 KiB
Markdown
257 lines
6.8 KiB
Markdown
# 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
|