agent-park/docs/api-testing-guide.md

API 测试指南

GET /api/events

获取所有事件:

curl http://localhost:3000/api/events

筛选特定年份:

curl "http://localhost:3000/api/events?year=2024"

限制返回数量:

curl "http://localhost:3000/api/events?limit=10"

分页:

curl "http://localhost:3000/api/events?offset=10&limit=10"

POST /api/events

创建单个事件:

curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '[
    {
      "title": "事件标题",
      "eventDate": "2023-03-14T00:00:00Z",
      "description": "事件描述(10-500字)",
      "imageUrl": "https://example.com/image.jpg"
    }
  ]'

批量创建事件:

curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '[
    { "title": "事件1", "eventDate": "2023-01-01T00:00:00Z", "description": "描述1", "imageUrl": "https://example.com/1.jpg" },
    { "title": "事件2", "eventDate": "2023-02-01T00:00:00Z", "description": "描述2", "imageUrl": "https://example.com/2.jpg" }
  ]'

包含可选字段:

curl -X POST http://localhost:3000/api/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '[
    {
      "title": "GPT-4 Release",
      "titleEn": "GPT-4 发布",
      "eventDate": "2023-03-14T00:00:00Z",
      "description": "OpenAI launches multimodal LLM",
      "descriptionEn": "OpenAI 发布多模态大语言模型",
      "imageUrl": "https://example.com/gpt4.jpg",
      "sourceUrl": "https://openai.com/blog/gpt-4"
    }
  ]'

验证规则

输入验证 (AIEventInputSchema)

• title: 1-200 字符（必填）
• titleEn: 最多 200 字符（可选）
• eventDate: ISO 8601 datetime 格式（必填）
• description: 10-500 字符（必填）
• descriptionEn: 最多 500 字符（可选）
• imageUrl: 有效 URL（必填）
• sourceUrl: 有效 URL（可选）

查询参数验证 (AIEventQuerySchema)

• year: 4位数字年份（可选）
• limit: 正整数（可选，默认 100）
• offset: 非负整数（可选，默认 0）

认证

所有 POST 请求必须在请求头中包含 API Key:

X-API-Key: YOUR_API_KEY

响应示例

成功响应 (POST)

{
  "created": 2,
  "total": 2
}

成功响应 (GET)

{
  "events": [
    {
      "id": "cmkwn6q0300004jjz4lobtkpf",
      "title": "Transformer论文",
      "titleEn": null,
      "eventDate": "2017-06-12T00:00:00.000Z",
      "description": "Google团队发表Transformer架构",
      "descriptionEn": null,
      "imageUrl": "https://images.unsplash.com/photo-1677442136019-21780ecad995?w=800",
      "sourceUrl": null,
      "createdAt": "2026-01-27T13:38:39.268Z",
      "updatedAt": "2026-01-27T13:38:39.268Z"
    }
  ]
}

错误响应

{
  "error": "Validation failed",
  "details": [
    {
      "code": "too_small",
      "path": ["0", "description"],
      "message": "String must contain at least 10 character(s)"
    }
  ]
}

测试记录

2025-01-27 测试结果

• ✅ GET /api/events - 返回空列表
• ✅ POST /api/events - 单个事件创建成功
• ✅ GET /api/events - 验证事件已创建（1个事件）
• ✅ POST /api/events - 批量创建成功（2个事件）
• ✅ GET /api/events?year=2018 - 年份筛选成功（返回2个事件）

所有基础功能测试通过！