update swagger

app/api/v1/daily_news.py

@@ -4,7 +4,8 @@ from datetime import datetime
 from typing import List, Dict, Any, Optional
 
 import pytz
-from fastapi import APIRouter
+from fastapi import APIRouter, Query, Path
+from fastapi.responses import JSONResponse
 
 from app.core import cache
 from app.services import crawler_factory
@@ -13,8 +14,43 @@ from app.utils.logger import log
 router = APIRouter()
 
 
-@router.get("/")
-def get_hot_news(date: str = None, platform: str = None):
+@router.get(
+    "/",
+    summary="获取单个平台的热门新闻",
+    description="从指定平台获取特定日期的热门新闻数据",
+    response_description="返回包含新闻列表的 JSON 对象",
+    responses={
+        200: {"description": "成功获取新闻数据"},
+        404: {"description": "平台不存在"}
+    }
+)
+def get_hot_news(
+    date: str = Query(
+        default=None,
+        description="日期，格式为 YYYY-MM-DD，默认为当天（北京时间）",
+        example="2024-01-15"
+    ),
+    platform: str = Query(
+        default=None,
+        description=f"平台代码，可选值：{', '.join(crawler_factory.keys())}",
+        example="weibo"
+    )
+):
+    """
+    **获取指定平台的热门新闻**
+    
+    根据指定的平台和日期获取热门新闻列表。数据来源于缓存，每 30 分钟更新一次。
+    
+    **参数说明：**
+    - `platform`: 必需，平台标识符（如：baidu, weibo, zhihu, github 等）
+    - `date`: 可选，查询日期，默认当天
+    
+    **支持的平台：**
+    - 综合资讯：百度、微博、知乎、抖音等
+    - 科技：GitHub、HackerNews、掘金、少数派等
+    - 财经：雪球、东方财富等
+    - 社区：贴吧、虎扑、豆瓣等
+    """
     if platform not in crawler_factory.keys():
         return {
             "status": "404",
@@ -41,16 +77,33 @@ def get_hot_news(date: str = None, platform: str = None):
     }
 
 
-@router.get("/all")
-def get_all_platforms_news(date: str = None):
+@router.get(
+    "/all",
+    summary="获取所有平台的热门新闻",
+    description="一次性获取所有支持平台的热门新闻数据",
+    response_description="返回包含所有平台新闻的 JSON 对象",
+    responses={
+        200: {"description": "成功获取所有平台新闻数据"}
+    }
+)
+def get_all_platforms_news(
+    date: str = Query(
+        default=None,
+        description="日期，格式为 YYYY-MM-DD，默认为当天",
+        example="2024-01-15"
+    )
+):
     """
-    获取所有平台的热门新闻
+    **获取所有平台的热门新闻**
     
-    Args:
-        date: 日期，格式为YYYY-MM-DD，默认为当天
+    一次性获取所有支持平台的热门新闻数据，适合需要全量数据的场景。
     
-    Returns:
-        包含所有平台新闻的字典，键为平台名称，值为新闻列表
+    **返回数据说明：**
+    返回一个字典，键为平台名称，值为该平台的新闻列表
+    
+    **注意事项：**
+    - 数据量较大，建议按需使用
+    - 部分平台可能没有缓存数据，返回空数组
     """
     if not date:
         date = datetime.now(pytz.timezone('Asia/Shanghai')).strftime("%Y-%m-%d")
@@ -76,17 +129,41 @@ def get_all_platforms_news(date: str = None):
     }
 
 
-@router.get("/multi")
-def get_multi_platforms_news(date: str = None, platforms: str = None):
+@router.get(
+    "/multi",
+    summary="获取多个平台的热门新闻",
+    description="批量获取指定平台的热门新闻数据",
+    response_description="返回包含指定平台新闻的 JSON 对象",
+    responses={
+        200: {"description": "成功获取多平台新闻数据"},
+        404: {"description": "平台参数无效"}
+    }
+)
+def get_multi_platforms_news(
+    date: str = Query(
+        default=None,
+        description="日期，格式为 YYYY-MM-DD，默认为当天",
+        example="2024-01-15"
+    ),
+    platforms: str = Query(
+        default=None,
+        description="平台列表，逗号分隔，例如：weibo,baidu,zhihu",
+        example="weibo,baidu,zhihu"
+    )
+):
     """
-    获取多个平台的热门新闻
+    **获取多个平台的热门新闻**
     
-    Args:
-        date: 日期，格式为YYYY-MM-DD，默认为当天
-        platforms: 平台列表，以逗号分隔，例如 "weibo,baidu,zhihu"
+    批量获取指定平台的热门新闻数据，相比 `/all` 接口更加灵活。
     
-    Returns:
-        包含指定平台新闻的字典，键为平台名称，值为新闻列表
+    **参数说明：**
+    - `platforms`: 必需，平台列表，逗号分隔
+    - `date`: 可选，查询日期
+    
+    **使用示例：**
+    ```
+    /multi?platforms=weibo,baidu,zhihu&date=2024-01-15
+    ```
     """
     if not date:
         date = datetime.now(pytz.timezone('Asia/Shanghai')).strftime("%Y-%m-%d")
@@ -131,19 +208,62 @@ def get_multi_platforms_news(date: str = None, platforms: str = None):
     }
 
 
-@router.get("/search")
-def search_news(keyword: str, date: str = None, platforms: str = None, limit: int = 20):
+@router.get(
+    "/search",
+    summary="搜索新闻",
+    description="按关键词搜索跨平台的热门新闻",
+    response_description="返回包含搜索结果的 JSON 对象",
+    responses={
+        200: {"description": "成功获取搜索结果"},
+        404: {"description": "无有效平台"}
+    }
+)
+def search_news(
+    keyword: str = Query(
+        default=...,
+        description="搜索关键词",
+        example="AI"
+    ),
+    date: str = Query(
+        default=None,
+        description="日期，格式为 YYYY-MM-DD，默认为当天",
+        example="2024-01-15"
+    ),
+    platforms: str = Query(
+        default=None,
+        description="平台列表，逗号分隔，默认搜索所有平台",
+        example="weibo,baidu,zhihu"
+    ),
+    limit: int = Query(
+        default=20,
+        ge=1,
+        le=100,
+        description="返回结果数量限制，范围 1-100",
+        example=20
+    )
+):
     """
-    搜索新闻
+    **搜索新闻**
     
-    Args:
-        keyword: 搜索关键词
-        date: 日期，格式为YYYY-MM-DD，默认为当天
-        platforms: 平台列表，以逗号分隔，例如 "weibo,baidu,zhihu"，默认搜索所有平台
-        limit: 返回结果数量限制，默认为20
+    按关键词在指定平台和日期的新闻中搜索相关内容。
     
-    Returns:
-        包含搜索结果的字典，键为状态码、数据、消息、总结果数量和搜索结果数量
+    **参数说明：**
+    - `keyword`: 必需，搜索关键词
+    - `date`: 可选，搜索日期
+    - `platforms`: 可选，限定搜索平台
+    - `limit`: 可选，返回结果数量，默认 20，最大 100
+    
+    **搜索逻辑：**
+    1. 从各平台获取新闻数据
+    2. 按关键词匹配标题
+    3. 按平台分组并按排名排序
+    4. 返回限定数量的结果
+    
+    **返回字段说明：**
+    - `source`: 新闻来源平台
+    - `rank`: 排名
+    - `category`: 分类
+    - `sub_category`: 子分类
     """
     if not date:
         date = datetime.now(pytz.timezone('Asia/Shanghai')).strftime("%Y-%m-%d")
@@ -184,7 +304,7 @@ def search_news(keyword: str, date: str = None, platforms: str = None, limit: in
                 if not isinstance(item, dict):
                     continue
                 
-                # 处理rank字段
+                # 处理 rank 字段
                 rank_value = ""
                 if "rank" in item and item["rank"]:
                     rank_value = str(item["rank"]).replace("#", "")
@@ -292,4 +412,3 @@ def _get_subcategory_for_platform(platform: str) -> str:
         "shaoshupai": "数码"
     }
     return subcategories.get(platform, "其他")
-