## API 文档

### Swagger UI

本项目使用 FastAPI 构建，内置 Swagger UI 文档，启动服务后自动可用。

**访问地址：**
- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI Schema**: http://localhost:8000/openapi.json

### 功能特性

✅ **交互式文档** - 可直接在浏览器中测试 API  
✅ **实时验证** - 自动验证请求参数和数据格式  
✅ **响应示例** - 每个接口都提供示例响应  
✅ **详细注释** - 包含完整的中文说明和使用场景  

### API 分类

#### 1. 每日热点新闻 (Daily News)

| 接口 | 描述 | 参数 |
|------|------|------|
| `GET /api/v1/dailynews/` | 获取单个平台的热门新闻 | `platform`(必需), `date`(可选) |
| `GET /api/v1/dailynews/all` | 获取所有平台的热门新闻 | `date`(可选) |
| `GET /api/v1/dailynews/multi` | 获取多个平台的热门新闻 | `platforms`(必需), `date`(可选) |
| `GET /api/v1/dailynews/search` | 搜索新闻 | `keyword`(必需), `platforms`, `date`, `limit` |

**支持的平台（22+）：**
- 综合资讯：百度、微博、知乎、抖音、今日头条
- 科技：GitHub、HackerNews、掘金、36Kr、少数派
- 财经：雪球、东方财富
- 社区：贴吧、虎扑、豆瓣、V2EX
- 视频：哔哩哔哩

#### 2. 网站工具 (Website Meta)

| 接口 | 描述 | 参数 |
|------|------|------|
| `GET /api/v1/tools/website-meta/` | 获取网站元数据 | `url`(必需) |

**返回信息：**
- 标题、描述、关键词
- Open Graph 标签（Facebook）
- Twitter Card 标签
- Favicon 图标地址

#### 3. 数据分析 (Analysis)

| 接口 | 描述 | 参数 |
|------|------|------|
| `GET /api/v1/analysis/trend` | 热点聚合分析 | `date`, `type` |
| `GET /api/v1/analysis/platform-comparison` | 平台对比分析 | `date` |
| `GET /api/v1/analysis/cross-platform` | 跨平台热点分析 | `date`, `refresh` |
| `GET /api/v1/analysis/advanced` | 高级分析 | `date`, `refresh` |
| `GET /api/v1/analysis/prediction` | 热点趋势预测 | `date` |
| `GET /api/v1/analysis/keyword-cloud` | 关键词云图 | `date`, `platforms`, `category`, `keyword_count` |
| `GET /api/v1/analysis/data-visualization` | 数据可视化分析 | `date`, `platforms`, `refresh` |
| `GET /api/v1/analysis/trend-forecast` | 热点趋势预测分析 | `date`, `time_range`, `refresh` |

#### 4. 健康检查 (Health)

| 接口 | 描述 |
|------|------|
| `GET /health` | 检查服务运行状态 |

### 使用示例

#### 示例 1：获取微博热搜

```bash
curl "http://localhost:8000/api/v1/dailynews/?platform=weibo&date=2024-01-15"
```

#### 示例 2：批量获取多平台新闻

```bash
curl "http://localhost:8000/api/v1/dailynews/multi?platforms=weibo,baidu,zhihu&date=2024-01-15"
```

#### 示例 3：搜索相关新闻

```bash
curl "http://localhost:8000/api/v1/dailynews/search?keyword=AI&platforms=weibo,zhihu&limit=10"
```

#### 示例 4：获取网站元数据

```bash
curl "http://localhost:8000/api/v1/tools/website-meta/?url=https://www.example.com"
```

#### 示例 5：获取热点趋势分析

```bash
curl "http://localhost:8000/api/v1/analysis/trend?type=main&date=2024-01-15"
```

### 响应格式

所有接口统一返回 JSON 格式：

```json
{
  "status": "200",
  "data": {...},
  "msg": "success"
}
```

**状态码说明：**
- `200`: 成功
- `404`: 资源不存在或参数错误
- `500`: 服务器内部错误

### 数据更新频率

- **热点新闻数据**：每 30 分钟更新一次
- **分析数据**：按需生成，支持缓存刷新
- **网站元数据**：首次请求抓取，缓存 60 秒

### 注意事项

1. **数据时效性**：所有数据仅供参考，非实时数据
2. **合法使用**：请遵守目标网站的 robots.txt 协议
3. **请求频率**：建议合理控制请求频率，避免触发反爬机制
4. **缓存机制**：大部分数据已缓存，重复请求不会增加目标网站负担