update swagger

app/api/v1/web_tools.py

@@ -9,15 +9,61 @@ from app.utils.logger import log
 
 import requests
 from bs4 import BeautifulSoup
-from fastapi import APIRouter
+from fastapi import APIRouter, Query
+from fastapi.responses import JSONResponse
 
 from app.core import cache
 
 router = APIRouter()
 
 
-@router.get("/")
-def get_meta(url: str = None):
+@router.get(
+    "/",
+    summary="获取网站元数据",
+    description="提取指定网页的元数据信息，包括标题、描述、关键词、Open Graph 标签、Twitter Card 标签和 favicon",
+    response_description="返回包含网站元数据的 JSON 对象",
+    responses={
+        200: {"description": "成功获取网站元数据"},
+        404: {"description": "URL 参数缺失或无法访问"}
+    }
+)
+def get_meta(
+    url: str = Query(
+        default=...,
+        description="要获取元数据的网页 URL",
+        example="https://www.example.com"
+    )
+):
+    """
+    **获取网站元数据**
+    
+    提取指定网页的各种元数据信息，支持标准 meta 标签、Open Graph 协议和 Twitter Card 协议。
+    
+    **功能特性：**
+    - 自动检测并提取页面标题、描述、关键词
+    - 支持 Open Graph 协议（Facebook）
+    - 支持 Twitter Card 协议
+    - 自动查找 favicon 图标地址
+    - 内置缓存机制，相同 URL 不会重复请求
+    
+    **提取字段说明：**
+    - `title`: 页面标题
+    - `description`: 页面描述
+    - `keywords`: 页面关键词
+    - `author`: 作者信息
+    - `og:*`: Open Graph 相关字段
+    - `twitter:*`: Twitter Card 相关字段
+    - `favicon_url`: 网站图标 URL
+    
+    **缓存策略：**
+    - 首次请求会实际抓取网页
+    - 后续请求从 Redis 缓存读取（TTL: 60 秒）
+    - 响应中 `cache` 字段标识是否来自缓存
+    
+    **注意事项：**
+    - 部分网站可能有反爬机制，使用 cloudscraper 进行绕过
+    - 动态渲染的内容可能无法完整获取
+    """
     if not url:
         return {
             "status": "404",