hot-news-api/README.md

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：获取微博热搜

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

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

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

示例 3：搜索相关新闻

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

示例 4：获取网站元数据

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

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

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

响应格式

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

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

状态码说明：

• 200: 成功
• 404: 资源不存在或参数错误
• 500: 服务器内部错误

数据更新频率

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

注意事项

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