wenzi/docs/api.md

API 文档

本文档详细说明了活动管理和API密钥管理相关的API端点。

1. 活动管理 (Activities)

1.1 创建活动

• Endpoint: POST /api/v1/activities

• 描述: 创建一个新的营销活动。

• 请求体: application/json

  {
    "name": "春季特惠活动",
    "startTime": "2025-03-01T10:00:00+08:00",
    "endTime": "2025-03-31T23:59:59+08:00"
  }
  

• 成功响应 (201 Created):

  {
    "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

  {
    "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

  {
    "activityId": 1,
    "name": "我的第一个密钥"
  }
  

• 成功响应 (201 Created):

  {
    "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 不存在。