129 lines
3.9 KiB
Markdown
129 lines
3.9 KiB
Markdown
## 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. **缓存机制**：大部分数据已缓存，重复请求不会增加目标网站负担
|