docs: add comprehensive API documentation with Swagger

apps/api/app/api/router.py

@@ -8,9 +8,45 @@ from app.api.routes.projects import router as projects_router
 from app.api.routes.upload import router as upload_router
 
 api_router = APIRouter()
-api_router.include_router(health_router, prefix="/health", tags=["health"])
-api_router.include_router(projects_router, prefix="/projects", tags=["projects"])
-api_router.include_router(asset_libraries_router, prefix="/asset-libraries", tags=["asset-libraries"])
-api_router.include_router(assets_router, prefix="/assets", tags=["assets"])
-api_router.include_router(ingest_jobs_router, prefix="/ingest-jobs", tags=["ingest-jobs"])
-api_router.include_router(upload_router, prefix="/upload", tags=["upload"])
+
+# Health check
+api_router.include_router(
+    health_router,
+    prefix="/health",
+    tags=["健康检查"],
+)
+
+# Projects
+api_router.include_router(
+    projects_router,
+    prefix="/projects",
+    tags=["项目管理"],
+)
+
+# Asset Libraries
+api_router.include_router(
+    asset_libraries_router,
+    prefix="/asset-libraries",
+    tags=["资产库管理"],
+)
+
+# Assets
+api_router.include_router(
+    assets_router,
+    prefix="/assets",
+    tags=["素材资产"],
+)
+
+# Ingest Jobs
+api_router.include_router(
+    ingest_jobs_router,
+    prefix="/ingest-jobs",
+    tags=["导入任务"],
+)
+
+# Upload
+api_router.include_router(
+    upload_router,
+    prefix="/upload",
+    tags=["文件上传"],
+)

apps/api/app/api/routes/upload.py

@@ -14,22 +14,54 @@ router = APIRouter()
 
 @router.post("", response_model=UploadAssetResponse)
 async def upload_asset(
-    file: UploadFile = File(...),
-    workspace_id: str = Form(...),
-    project_id: str = Form(...),
-    library_id: str = Form(...),
+    file: UploadFile = File(..., description="要上传的文件（视频、音频、图片等）"),
+    workspace_id: str = Form(..., description="工作空间 ID"),
+    project_id: str = Form(..., description="项目 ID"),
+    library_id: str = Form(..., description="资产库 ID"),
     ingest_job_repository: InMemoryIngestJobRepository = Depends(get_ingest_job_repository),
     storage_service: MinIOService = Depends(get_minio_service),
 ) -> UploadAssetResponse:
     """
-    Upload asset and trigger ingest pipeline.
+    上传素材文件并触发导入流水线。
     
-    Real implementation:
-    1. Accept multipart/form-data with file
-    2. Store file to MinIO object storage
-    3. Generate storage_key
-    4. Submit ingest job
-    5. Enqueue worker task
+    ## 功能说明
+    
+    1. **接收文件**：支持 multipart/form-data 上传
+    2. **存储到 MinIO**：自动存储到对象存储
+    3. **生成存储键**：格式为 `uploads/{id}/{filename}`
+    4. **提交导入任务**：创建 IngestJob 记录
+    5. **异步处理**：通过 Celery 队列处理
+    
+    ## 支持的文件类型
+    
+    - **视频**：MP4, MOV, AVI, MKV 等
+    - **音频**：MP3, WAV, AAC 等
+    - **图片**：JPG, PNG, GIF, WebP 等
+    
+    ## 请求示例
+    
+    ```bash
+    curl -X POST "http://localhost:8000/api/v1/upload" \
+      -H "Content-Type: multipart/form-data" \
+      -F "file=@/path/to/video.mp4" \
+      -F "workspace_id=ws_123" \
+      -F "project_id=proj_456" \
+      -F "library_id=lib_789"
+    ```
+    
+    ## 响应说明
+    
+    - `storage_key`: 文件在 MinIO 中的存储路径
+    - `ingest_job_id`: 导入任务 ID，用于追踪处理状态
+    - `url`: 文件的公开访问 URL
+    
+    ## 后续流程
+    
+    上传成功后，系统会：
+    1. 自动提取文件元数据（时长、分辨率等）
+    2. 生成缩略图
+    3. 进行场景分割（视频）
+    4. 创建 Asset 记录
     """
     # Generate storage key
     file_id = uuid4().hex[:8]