# Discovery API 接口文档 ## 简介 Discovery API是一个用于发现和搜索创作者的接口。它提供了创作者搜索、搜索会话管理等功能。所有API响应均遵循统一格式： ```json { "code": 200, // 状态码，200表示成功 "message": "操作成功", // 操作提示消息 "data": { // 实际数据 // 具体内容 } } ``` ## 使用Apifox测试接口 1. 下载并安装Apifox: https://www.apifox.cn/ 2. 创建新项目，命名为"Creator Discovery" 3. 导入API或手动创建以下接口 ## API 接口列表 ### 1. 搜索创作者 - **URL**: `http://localhost:8000/api/discovery/creators/search/` - **方法**: POST - **描述**: 根据条件搜索创作者，并创建新的搜索会话 - **请求参数**: ```json { "query": "创作者", "category": "Health", "ecommerce_level": "L5", "exposure_level": "KOL-2" } ``` - **响应示例**: ```json { "code": 200, "message": "搜索创作者成功", "data": { "id": 4, "creators": [ { "id": 37, "name": "Mock Creator 5", "avatar": null, "category": "Health", "ecommerce_level": "L5", "exposure_level": "KOL-2", "followers": 162.2, "gmv": 534.1, "items_sold": 18.1, "avg_video_views": 1.9, "has_ecommerce": false, "tiktok_url": null, "session": 4 } ], "session_number": 4, "creator_count": 1, "shoppable_creators": 0, "avg_followers": 162.2, "avg_gmv": 534.1, "avg_video_views": 1.9, "date_created": "2023-10-02" } } ``` ### 2. 获取搜索会话列表 - **URL**: `http://localhost:8000/api/discovery/sessions/` - **方法**: GET - **描述**: 获取所有搜索会话的历史记录 - **查询参数**: - `page`: 页码，默认为1 - `page_size`: 每页条数，默认为20，最大为100 - **响应示例**: ```json { "code": 200, "message": "获取数据成功", "data": { "count": 3, "next": "http://localhost:8000/api/discovery/sessions/?page=2", "previous": null, "results": [ { "id": 1, "session_number": 1, "creator_count": 42, "shoppable_creators": 24, "avg_followers": 162.2, "avg_gmv": 534.1, "avg_video_views": 1.9, "date_created": "2024-01-06" }, { "id": 2, "session_number": 2, "creator_count": 53, "shoppable_creators": 13, "avg_followers": 162.2, "avg_gmv": 534.1, "avg_video_views": 1.9, "date_created": "2022-01-07" } ] } } ``` ### 3. 获取搜索会话详情 - **URL**: `http://localhost:8000/api/discovery/sessions/{id}/` - **方法**: GET - **描述**: 获取特定搜索会话的详细信息，包含该会话中的所有创作者 - **请求参数**: 路径参数 `id` - **响应示例**: ```json { "code": 200, "message": "获取搜索会话详情成功", "data": { "id": 1, "creators": [ { "id": 1, "name": "Creator 1 in Session 1", "avatar": null, "category": "Phones & Electronics", "ecommerce_level": "L2", "exposure_level": "KOC-1", "followers": 162.2, "gmv": 534.1, "items_sold": 18.1, "avg_video_views": 1.9, "has_ecommerce": true, "tiktok_url": null, "session": 1 }, { "id": 2, "name": "Creator 9 in Session 1", "avatar": null, "category": "Womenswear & Underwear", "ecommerce_level": "L3", "exposure_level": "KOL-3", "followers": 162.2, "gmv": 534.1, "items_sold": 18.1, "avg_video_views": 1.9, "has_ecommerce": false, "tiktok_url": null, "session": 1 } ], "session_number": 1, "creator_count": 42, "shoppable_creators": 24, "avg_followers": 162.2, "avg_gmv": 534.1, "avg_video_views": 1.9, "date_created": "2024-01-06" } } ``` ### 4. 获取会话中的创作者 - **URL**: `http://localhost:8000/api/discovery/sessions/{id}/results/` - **方法**: GET - **描述**: 获取特定会话中的所有创作者 - **请求参数**: - 路径参数 `id` - 查询参数 `page`、`page_size`（分页参数） - **响应示例**: ```json { "code": 200, "message": "获取数据成功", "data": { "count": 42, "next": "http://localhost:8000/api/discovery/sessions/1/results/?page=2", "previous": null, "results": [ { "id": 1, "name": "Creator 1 in Session 1", "avatar": null, "category": "Phones & Electronics", "ecommerce_level": "L2", "exposure_level": "KOC-1", "followers": 162.2, "gmv": 534.1, "items_sold": 18.1, "avg_video_views": 1.9, "has_ecommerce": true, "tiktok_url": null, "session": 1 }, { "id": 2, "name": "Creator 9 in Session 1", "avatar": null, "category": "Womenswear & Underwear", "ecommerce_level": "L3", "exposure_level": "KOL-3", "followers": 162.2, "gmv": 534.1, "items_sold": 18.1, "avg_video_views": 1.9, "has_ecommerce": false, "tiktok_url": null, "session": 1 } ] } } ``` ### 5. 获取所有创作者 - **URL**: `http://localhost:8000/api/discovery/creators/` - **方法**: GET - **描述**: 获取系统中的所有创作者 - **请求参数**: 查询参数 `page`、`page_size`（分页参数） - **响应示例**: ```json { "code": 200, "message": "获取数据成功", "data": { "count": 150, "next": "http://localhost:8000/api/discovery/creators/?page=2", "previous": null, "results": [ { "id": 1, "name": "Creator 1 in Session 1", "avatar": null, "category": "Phones & Electronics", "ecommerce_level": "L2", "exposure_level": "KOC-1", "followers": 162.2, "gmv": 534.1, "items_sold": 18.1, "avg_video_views": 1.9, "has_ecommerce": true, "tiktok_url": null, "session": 1 }, // 更多创作者... ] } } ``` ### 6. 获取创作者详情 - **URL**: `http://localhost:8000/api/discovery/creators/{id}/` - **方法**: GET - **描述**: 获取特定创作者的详细信息 - **请求参数**: 路径参数 `id` - **响应示例**: ```json { "code": 200, "message": "获取创作者详情成功", "data": { "id": 1, "name": "Creator 1 in Session 1", "avatar": null, "category": "Phones & Electronics", "ecommerce_level": "L2", "exposure_level": "KOC-1", "followers": 162.2, "gmv": 534.1, "items_sold": 18.1, "avg_video_views": 1.9, "has_ecommerce": true, "tiktok_url": null, "session": 1 } } ``` ## 在Apifox中设置环境变量 创建一个名为"本地开发环境"的环境，设置以下变量： - `baseUrl`: `http://localhost:8000/api` 这样可以在所有请求中使用`{{baseUrl}}/discovery/...`来替代完整URL。 ## 测试流程示例 1. 启动Django服务器：`python manage.py runserver` 2. 在Apifox中发送请求"获取搜索会话列表" 3. 在响应中选择一个会话ID 4. 使用该ID获取会话详情 5. 使用"搜索创作者"接口创建新的搜索会话 6. 验证新创建的会话是否出现在会话列表中 ## 在Apifox中导入API 1. 在Apifox中，点击"导入"按钮 2. 选择"导入API" 3. 将本文档中的API信息整理成集合导入 4. 设置每个接口的请求和响应格式 5. 设置示例响应 ## 注意事项 - 所有API响应均遵循统一的格式：`code`、`message`和`data` - 分页接口返回格式为：`{ "code": 200, "message": "获取数据成功", "data": { "count": 总数, "next": 下一页URL, "previous": 上一页URL, "results": [] } }` - 即使发生错误，HTTP状态码始终为200，错误信息在响应体的`code`和`message`中提供 - 接口不需要认证，可直接访问