100 lines
2.5 KiB
Markdown
100 lines
2.5 KiB
Markdown
# API 文档
|
||
|
||
本文档详细说明了活动管理和API密钥管理相关的API端点。
|
||
|
||
## 1. 活动管理 (Activities)
|
||
|
||
### 1.1 创建活动
|
||
|
||
- **Endpoint**: `POST /api/v1/activities`
|
||
- **描述**: 创建一个新的营销活动。
|
||
- **请求体**: `application/json`
|
||
|
||
```json
|
||
{
|
||
"name": "春季特惠活动",
|
||
"startTime": "2025-03-01T10:00:00+08:00",
|
||
"endTime": "2025-03-31T23:59:59+08:00"
|
||
}
|
||
```
|
||
|
||
- **成功响应 (201 Created)**:
|
||
|
||
```json
|
||
{
|
||
"id": 1,
|
||
"name": "春季特惠活动",
|
||
"startTime": "2025-03-01T10:00:00+08:00",
|
||
"endTime": "2025-03-31T23:59:59+08:00",
|
||
// ... 其他活动属性
|
||
}
|
||
```
|
||
|
||
- **失败响应**:
|
||
- `400 Bad Request`: 如果请求数据无效（例如，名称为空或结束时间早于开始时间）。
|
||
|
||
### 1.2 更新活动
|
||
|
||
- **Endpoint**: `PUT /api/v1/activities/{id}`
|
||
- **描述**: 更新一个已存在的活动。
|
||
- **路径参数**: `id` (long) - 活动的唯一标识符。
|
||
- **请求体**: `application/json`
|
||
|
||
```json
|
||
{
|
||
"name": "春季特惠活动（升级版）",
|
||
"startTime": "2025-03-01T10:00:00+08:00",
|
||
"endTime": "2025-04-15T23:59:59+08:00"
|
||
}
|
||
```
|
||
|
||
- **成功响应 (200 OK)**: 返回更新后的活动对象。
|
||
- **失败响应**:
|
||
- `400 Bad Request`: 如果请求数据无效。
|
||
- `404 Not Found`: 如果指定的 `id` 不存在。
|
||
|
||
### 1.3 获取活动详情
|
||
|
||
- **Endpoint**: `GET /api/v1/activities/{id}`
|
||
- **描述**: 获取指定ID的活动详情。
|
||
- **路径参数**: `id` (long) - 活动的唯一标识符。
|
||
- **成功响应 (200 OK)**: 返回活动对象。
|
||
- **失败响应**:
|
||
- `404 Not Found`: 如果指定的 `id` 不存在。
|
||
|
||
## 2. API密钥管理 (API Keys)
|
||
|
||
### 2.1 创建API密钥
|
||
|
||
- **Endpoint**: `POST /api/v1/api-keys`
|
||
- **描述**: 为指定的活动创建一个新的API密钥。密钥仅在本次响应中明文返回，请立即保存。
|
||
- **请求体**: `application/json`
|
||
|
||
```json
|
||
{
|
||
"activityId": 1,
|
||
"name": "我的第一个密钥"
|
||
}
|
||
```
|
||
|
||
- **成功响应 (201 Created)**:
|
||
|
||
```json
|
||
{
|
||
"apiKey": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
|
||
}
|
||
```
|
||
|
||
- **失败响应**:
|
||
- `400 Bad Request`: 如果请求数据无效（例如，`activityId` 或 `name` 为空）。
|
||
- `404 Not Found`: 如果 `activityId` 不存在。
|
||
|
||
### 2.2 吊销API密钥
|
||
|
||
- **Endpoint**: `DELETE /api/v1/api-keys/{id}`
|
||
- **描述**: 吊销（删除）一个API密钥。
|
||
- **路径参数**: `id` (long) - API密钥的唯一标识符。
|
||
- **成功响应 (204 No Content)**: 无响应体。
|
||
- **失败响应**:
|
||
- `404 Not Found`: 如果指定的 `id` 不存在。
|