feat: 为所有API添加Pydantic响应模型，完善Swagger文档

- 新增统一的响应模型基础设施(schemas/response.py)
- 为37个API接口添加response_model参数
- 统一响应格式为{code, msg, data}结构
- 完善Swagger文档的返回值预览功能
- 支持分页、详情、操作结果等多种响应类型
- 提供完整的中文字段描述和类型安全保证

改动模块：
- 用户管理、认证相关、角色管理
- 菜单管理、部门管理、API权限管理
- 审计日志、文件管理等所有API模块

Author: JiayuXu

src/api/v1/apis/apis.py

@@ -1,14 +1,17 @@
+import json
+
 from fastapi import APIRouter, Query
 from tortoise.expressions import Q
 
 from repositories.api import api_repository
 from schemas import Success, SuccessExtra
-from schemas.apis import *
+from schemas.apis import ApiCreate, ApiUpdate
+from schemas.response import ApiInfo, ApiListResponse, ResponseBase
 
 router = APIRouter()
 
 
-@router.get("/list", summary="查看API列表")
+@router.get("/list", summary="查看API列表", response_model=ApiListResponse)
 async def list_api(
     page: int = Query(1, description="页码"),
     page_size: int = Query(10, description="每页数量"),
@@ -27,43 +30,49 @@ async def list_api(
         page=page, page_size=page_size, search=q, order=["tags", "id"]
     )
     data = [await obj.to_dict() for obj in api_objs]
-    return SuccessExtra(data=data, total=total, page=page, page_size=page_size)
+    result = SuccessExtra(data=data, total=total, page=page, page_size=page_size)
+    return json.loads(result.body)
 
 
-@router.get("/get", summary="查看Api")
+@router.get("/get", summary="查看Api", response_model=ResponseBase[ApiInfo])
 async def get_api(
     id: int = Query(..., description="Api"),
 ):
     api_obj = await api_repository.get(id=id)
     data = await api_obj.to_dict()
-    return Success(data=data)
+    result = Success(data=data)
+    return json.loads(result.body)
 
 
-@router.post("/create", summary="创建Api")
+@router.post("/create", summary="创建Api", response_model=ResponseBase[None])
 async def create_api(
     api_in: ApiCreate,
 ):
     await api_repository.create(obj_in=api_in)
-    return Success(msg="Created Successfully")
+    result = Success(msg="Created Successfully")
+    return json.loads(result.body)
 
 
-@router.post("/update", summary="更新Api")
+@router.post("/update", summary="更新Api", response_model=ResponseBase[None])
 async def update_api(
     api_in: ApiUpdate,
 ):
     await api_repository.update(id=api_in.id, obj_in=api_in)
-    return Success(msg="Update Successfully")
+    result = Success(msg="Update Successfully")
+    return json.loads(result.body)
 
 
-@router.delete("/delete", summary="删除Api")
+@router.delete("/delete", summary="删除Api", response_model=ResponseBase[None])
 async def delete_api(
     api_id: int = Query(..., description="ApiID"),
 ):
     await api_repository.remove(id=api_id)
-    return Success(msg="Deleted Success")
+    result = Success(msg="Deleted Success")
+    return json.loads(result.body)
 
 
-@router.post("/refresh", summary="刷新API列表")
+@router.post("/refresh", summary="刷新API列表", response_model=ResponseBase[None])
 async def refresh_api():
     await api_repository.refresh_api()
-    return Success(msg="OK")
+    result = Success(msg="OK")
+    return json.loads(result.body)

src/api/v1/auditlog/auditlog.py

@@ -1,16 +1,17 @@
+import json
 from datetime import datetime
 
 from fastapi import APIRouter, Query
 from tortoise.expressions import Q
 
 from models.admin import AuditLog
 from schemas import SuccessExtra
-from schemas.apis import *
+from schemas.response import AuditLogListResponse
 
 router = APIRouter()
 
 
-@router.get("/list", summary="查看操作日志")
+@router.get("/list", summary="查看操作日志", response_model=AuditLogListResponse)
 async def get_audit_log_list(
     page: int = Query(1, description="页码"),
     page_size: int = Query(10, description="每页数量"),
@@ -48,4 +49,5 @@ async def get_audit_log_list(
     )
     total = await AuditLog.filter(q).count()
     data = [await audit_log.to_dict() for audit_log in audit_log_objs]
-    return SuccessExtra(data=data, total=total, page=page, page_size=page_size)
+    result = SuccessExtra(data=data, total=total, page=page, page_size=page_size)
+    return json.loads(result.body)

src/api/v1/base/base.py

@@ -1,3 +1,4 @@
+import json
 import os
 from datetime import UTC, datetime
 
@@ -16,6 +17,14 @@
     RefreshTokenRequest,
     TokenRefreshOut,
 )
+from schemas.response import (
+    CurrentUserResponse,
+    HealthInfo,
+    HealthResponse,
+    TokenResponse,
+    VersionInfo,
+    VersionResponse,
+)
 from settings import settings
 from utils.jwt import create_token_pair, verify_token
 
@@ -29,7 +38,6 @@ def apply_rate_limit(rate="5/minute"):
     """根据环境应用限流装饰器"""
 
     def decorator(func):
-        import os
 
         if os.getenv("TESTING", "false").lower() == "true":
             return func  # 测试环境不应用限流
@@ -38,7 +46,7 @@ def decorator(func):
     return decorator
 
 
-@router.post("/access_token", summary="获取token")
+@router.post("/access_token", summary="获取token", response_model=TokenResponse)
 @apply_rate_limit()
 async def login_access_token(request: Request, credentials: CredentialsSchema):
     user: User = await user_repository.authenticate(credentials)
@@ -55,10 +63,11 @@ async def login_access_token(request: Request, credentials: CredentialsSchema):
         username=user.username,
         expires_in=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES * 60,
     )
-    return Success(data=data.model_dump())
+    result = Success(data=data.model_dump())
+    return json.loads(result.body)
 
 
-@router.post("/refresh_token", summary="刷新token")
+@router.post("/refresh_token", summary="刷新token", response_model=TokenResponse)
 @apply_rate_limit("10/minute")
 async def refresh_access_token(request: Request, refresh_request: RefreshTokenRequest):
     """
@@ -84,43 +93,45 @@ async def refresh_access_token(request: Request, refresh_request: RefreshTokenRe
             expires_in=settings.JWT_ACCESS_TOKEN_EXPIRE_MINUTES * 60,
         )
 
-        return Success(data=data.model_dump())
+        result = Success(data=data.model_dump())
+        return json.loads(result.body)
 
     except Exception:
-        return Fail(code=401, msg="令牌无效或已过期")
+        result = Fail(code=401, msg="令牌无效或已过期")
+        return json.loads(result.body)
 
 
-@router.get("/userinfo", summary="查看用户信息")
+@router.get("/userinfo", summary="查看用户信息", response_model=CurrentUserResponse)
 async def get_userinfo(current_user: User = DependAuth):
     user_id = CTX_USER_ID.get()
     user_obj = await user_repository.get(id=user_id)
     user_dict = await user_obj.to_dict()
-    return Success(data=user_dict)
+    result = Success(data=user_dict)
+    return json.loads(result.body)
 
 
-@router.get("/health", summary="健康检查")
+@router.get("/health", summary="健康检查", response_model=HealthResponse)
 async def health_check():
     """系统健康检查"""
-    return {
-        "status": "healthy",
-        "timestamp": datetime.now(UTC).isoformat(),
-        "version": settings.VERSION,
-        "environment": settings.APP_ENV,
-        "service": "FastAPI Backend Template",
-    }
+    health_data = HealthInfo(
+        status="healthy",
+        timestamp=datetime.now(UTC),
+        environment=settings.APP_ENV,
+        database="connected"
+    )
+    return HealthResponse(code=200, msg="OK", data=health_data)
 
 
-@router.get("/version", summary="版本信息")
+@router.get("/version", summary="版本信息", response_model=VersionResponse)
 async def get_version():
     """获取API版本信息"""
-    return {
-        "version": settings.VERSION,
-        "app_title": settings.APP_TITLE,
-        "project_name": settings.PROJECT_NAME,
-        "build": os.getenv("BUILD_NUMBER", "dev"),
-        "commit": os.getenv("GIT_COMMIT", "unknown"),
-        "python_version": os.getenv("PYTHON_VERSION", "3.11+"),
-    }
+    version_data = VersionInfo(
+        app_name=settings.APP_TITLE,
+        version=settings.VERSION,
+        api_version="v1",
+        environment=settings.APP_ENV
+    )
+    return VersionResponse(code=200, msg="OK", data=version_data)
 
 
 # @router.get("/usermenu", summary="查看用户菜单", dependencies=[DependAuth])

src/api/v1/depts/depts.py

@@ -1,48 +1,56 @@
+import json
+
 from fastapi import APIRouter, Query
 
 from repositories.dept import dept_repository
 from schemas import Success
-from schemas.depts import *
+from schemas.depts import DeptCreate, DeptUpdate
+from schemas.response import DeptDetailResponse, DeptListResponse, ResponseBase
 
 router = APIRouter()
 
 
-@router.get("/list", summary="查看部门列表")
+@router.get("/list", summary="查看部门列表", response_model=DeptListResponse)
 async def list_dept(
     name: str = Query(None, description="部门名称"),
 ):
     dept_tree = await dept_repository.get_dept_tree(name)
-    return Success(data=dept_tree)
+    result = Success(data=dept_tree)
+    return json.loads(result.body)
 
 
-@router.get("/get", summary="查看部门")
+@router.get("/get", summary="查看部门", response_model=DeptDetailResponse)
 async def get_dept(
     id: int = Query(..., description="部门ID"),
 ):
     dept_obj = await dept_repository.get(id=id)
     data = await dept_obj.to_dict()
-    return Success(data=data)
+    result = Success(data=data)
+    return json.loads(result.body)
 
 
-@router.post("/create", summary="创建部门")
+@router.post("/create", summary="创建部门", response_model=ResponseBase[None])
 async def create_dept(
     dept_in: DeptCreate,
 ):
     await dept_repository.create_dept(obj_in=dept_in)
-    return Success(msg="Created Successfully")
+    result = Success(msg="Created Successfully")
+    return json.loads(result.body)
 
 
-@router.post("/update", summary="更新部门")
+@router.post("/update", summary="更新部门", response_model=ResponseBase[None])
 async def update_dept(
     dept_in: DeptUpdate,
 ):
     await dept_repository.update_dept(obj_in=dept_in)
-    return Success(msg="Update Successfully")
+    result = Success(msg="Update Successfully")
+    return json.loads(result.body)
 
 
-@router.delete("/delete", summary="删除部门")
+@router.delete("/delete", summary="删除部门", response_model=ResponseBase[None])
 async def delete_dept(
     dept_id: int = Query(..., description="部门ID"),
 ):
     await dept_repository.delete_dept(dept_id=dept_id)
-    return Success(msg="Deleted Success")
+    result = Success(msg="Deleted Success")
+    return json.loads(result.body)

src/api/v1/files/files.py

@@ -1,6 +1,9 @@
+import json
+
 from fastapi import APIRouter, File, UploadFile
 
 from core.dependency import DependAuth
+from schemas.response import ResponseBase
 from services.file_service import file_service
 
 router = APIRouter()
@@ -10,6 +13,7 @@
     "/upload",
     summary="上传文件",
     dependencies=[DependAuth],
+    response_model=ResponseBase[dict],
 )
 async def upload_file(
     file: UploadFile = File(..., description="要上传的文件"),
@@ -23,4 +27,5 @@ async def upload_file(
     Returns:
         上传成功的响应，包含文件信息
     """
-    return await file_service.upload_file(file)
+    result = await file_service.upload_file(file)
+    return json.loads(result.body)