253 lines
5.7 KiB
Markdown
253 lines
5.7 KiB
Markdown
# 固件管理 API 接口文档
|
||
|
||
## 基本信息
|
||
|
||
- **Base URL**: `http://localhost:8080`
|
||
- **接口前缀**: `/firmware`
|
||
- **请求头**:
|
||
- `Accept-Language`: `zh_CN` 或 `en_US`（可选，默认中文）
|
||
|
||
## 统一响应格式
|
||
|
||
所有接口返回格式统一为：
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
**字段说明：**
|
||
- `code`: 状态码（200-成功，500-失败）
|
||
- `message`: 提示消息（支持中英文国际化）
|
||
- `data`: 返回的数据
|
||
- `success`: 是否成功（true/false）
|
||
|
||
---
|
||
|
||
## 1. 根据ID查询固件
|
||
|
||
**接口描述：** 根据固件ID查询固件详细信息
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**请求路径：** `/firmware/{id}`
|
||
|
||
**路径参数：**
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | Long | 是 | 固件ID |
|
||
|
||
**请求示例：**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/firmware/1" \
|
||
-H "Accept-Language: zh_CN"
|
||
```
|
||
|
||
**成功响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"id": 1,
|
||
"firmwareName": "固件 v2.0.0",
|
||
"firmwareSize": 2097152,
|
||
"firmwareDescription": "新版本固件，优化性能",
|
||
"firmwareType": "主控固件",
|
||
"downloadUrl": "https://example.com/firmware/v2.0.0.bin",
|
||
"createTime": "2025-01-15 10:30:00",
|
||
"updateTime": "2025-01-15 10:30:00"
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
**失败响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "固件不存在",
|
||
"data": null,
|
||
"success": false
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 分页查询固件列表
|
||
|
||
**接口描述：** 分页查询固件列表，支持按固件名称和固件类型筛选
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**请求路径：** `/firmware/page`
|
||
|
||
**请求参数（Query）：**
|
||
|
||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||
|--------|------|------|--------|------|
|
||
| current | Long | 否 | 1 | 当前页码 |
|
||
| size | Long | 否 | 10 | 每页大小 |
|
||
| firmwareName | String | 否 | - | 固件名称（模糊查询） |
|
||
| firmwareType | String | 否 | - | 固件类型（精确查询） |
|
||
|
||
**请求示例：**
|
||
|
||
```bash
|
||
# 查询第1页，每页10条
|
||
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10" \
|
||
-H "Accept-Language: zh_CN"
|
||
|
||
# 按固件名称模糊查询
|
||
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareName=v2"
|
||
|
||
# 按固件类型查询
|
||
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareType=主控固件"
|
||
|
||
# 组合查询
|
||
curl -X GET "http://localhost:8080/firmware/page?current=1&size=10&firmwareName=v2&firmwareType=主控固件"
|
||
```
|
||
|
||
**成功响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"firmwareName": "固件 v2.0.0",
|
||
"firmwareSize": 2097152,
|
||
"firmwareDescription": "新版本固件，优化性能",
|
||
"firmwareType": "主控固件",
|
||
"downloadUrl": "https://example.com/firmware/v2.0.0.bin",
|
||
"createTime": "2025-01-15 10:30:00",
|
||
"updateTime": "2025-01-15 10:30:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"firmwareName": "固件 v1.0.1",
|
||
"firmwareSize": 1049600,
|
||
"firmwareDescription": "修复了若干 bug 的版本",
|
||
"firmwareType": "主控固件",
|
||
"downloadUrl": "https://example.com/firmware/v1.0.1.bin",
|
||
"createTime": "2025-01-14 09:20:00",
|
||
"updateTime": "2025-01-14 09:20:00"
|
||
}
|
||
],
|
||
"total": 2,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 1
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
**响应字段说明：**
|
||
- `records`: 当前页的数据列表
|
||
- `total`: 总记录数
|
||
- `size`: 每页大小
|
||
- `current`: 当前页码
|
||
- `pages`: 总页数
|
||
|
||
---
|
||
|
||
## 3. 查询所有固件
|
||
|
||
**接口描述：** 查询所有固件列表（不分页）
|
||
|
||
**请求方式：** `GET`
|
||
|
||
**请求路径：** `/firmware/list`
|
||
|
||
**请求示例：**
|
||
|
||
```bash
|
||
curl -X GET "http://localhost:8080/firmware/list" \
|
||
-H "Accept-Language: zh_CN"
|
||
```
|
||
|
||
**成功响应示例：**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "操作成功",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"firmwareName": "固件 v2.0.0",
|
||
"firmwareSize": 2097152,
|
||
"firmwareDescription": "新版本固件，优化性能",
|
||
"firmwareType": "主控固件",
|
||
"downloadUrl": "https://example.com/firmware/v2.0.0.bin",
|
||
"createTime": "2025-01-15 10:30:00",
|
||
"updateTime": "2025-01-15 10:30:00"
|
||
},
|
||
{
|
||
"id": 2,
|
||
"firmwareName": "固件 v1.0.1",
|
||
"firmwareSize": 1049600,
|
||
"firmwareDescription": "修复了若干 bug 的版本",
|
||
"firmwareType": "主控固件",
|
||
"downloadUrl": "https://example.com/firmware/v1.0.1.bin",
|
||
"createTime": "2025-01-14 09:20:00",
|
||
"updateTime": "2025-01-14 09:20:00"
|
||
}
|
||
],
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 请求成功 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 国际化支持
|
||
|
||
接口支持中英文双语，通过请求头 `Accept-Language` 或 `lang` 指定语言：
|
||
|
||
- `zh_CN` - 中文（默认）
|
||
- `en_US` - 英文
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
# 中文响应
|
||
curl -X GET "http://localhost:8080/firmware/1" \
|
||
-H "Accept-Language: zh_CN"
|
||
|
||
# 英文响应
|
||
curl -X GET "http://localhost:8080/firmware/1" \
|
||
-H "Accept-Language: en_US"
|
||
```
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **文件大小单位**：`firmwareSize` 字段的单位是字节（Byte）
|
||
2. **时间格式**：`createTime` 和 `updateTime` 的格式为 `yyyy-MM-dd HH:mm:ss`
|
||
3. **分页默认排序**：分页查询默认按创建时间倒序排列（最新的在前面）
|
||
4. **模糊查询**：分页查询中的 `firmwareName` 参数支持模糊匹配
|
||
5. **类型查询**：分页查询中的 `firmwareType` 参数是精确匹配
|
||
6. **国际化**：通过 `Accept-Language` 请求头可切换中英文响应消息
|