优化API文档，添加参数描述和示例

app/api/v1/endpoints/user_management.py

@@ -4,7 +4,7 @@
 演示权限控制的使用
 """
 from typing import List
-from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi import APIRouter, Depends, HTTPException, status, Path, Query
 from app.domain.schemas.user import UserResponse, UserUpdate, UserCreate
 from app.domain.models.role import UserRole
 from app.domain.schemas.user import UserInDB
@@ -14,22 +14,24 @@ from app.auth.permissions import get_current_admin, require_role, check_resource
 
 router = APIRouter()
 
-@router.get("/", response_model=List[UserResponse])
+@router.get("/", summary="列出所有用户", description="获取用户列表（仅管理员）", response_model=List[UserResponse])
 async def list_users(
-    skip: int = 0,
-    limit: int = 100,
+    skip: int = Query(0, ge=0, description="跳过的用户数"),
+    limit: int = Query(100, ge=1, le=1000, description="返回的最大用户数"),
     current_user: UserInDB = Depends(require_role(UserRole.ADMIN)),
     user_repo: UserRepository = Depends(get_user_repository)
 ) -> List[UserResponse]:
     """
-    获取用户列表（仅管理员）
+    获取用户列表
+    
+    获取系统中所有的用户信息（需要管理员权限）
     """
     users = await user_repo.get_all_users(skip=skip, limit=limit)
     return [UserResponse.model_validate(user) for user in users]
 
-@router.get("/{user_id}", response_model=UserResponse)
+@router.get("/{user_id}", summary="获取用户详情", description="获取指定用户的详细信息", response_model=UserResponse)
 async def get_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_active_user),
     user_repo: UserRepository = Depends(get_user_repository)
 ) -> UserResponse:
@@ -54,10 +56,10 @@ async def get_user(
     
     return UserResponse.model_validate(user)
 
-@router.put("/{user_id}", response_model=UserResponse)
+@router.put("/{user_id}", summary="更新用户信息", description="更新指定用户的信息", response_model=UserResponse)
 async def update_user(
-    user_id: int,
-    user_update: UserUpdate,
+    user_id: int = Path(..., gt=0, description="用户ID"),
+    user_update: UserUpdate = None,
     current_user: UserInDB = Depends(get_current_active_user),
     user_repo: UserRepository = Depends(get_user_repository)
 ) -> UserResponse:
@@ -107,14 +109,16 @@ async def update_user(
     
     return UserResponse.model_validate(updated_user)
 
-@router.delete("/{user_id}")
+@router.delete("/{user_id}", summary="删除用户", description="删除指定用户（仅管理员）")
 async def delete_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_admin),
     user_repo: UserRepository = Depends(get_user_repository)
 ) -> dict:
     """
-    删除用户（仅管理员）
+    删除用户
+    
+    删除指定用户（需要管理员权限，不能删除自己）
     """
     # 不能删除自己
     if current_user.id == user_id:
@@ -132,14 +136,16 @@ async def delete_user(
     
     return {"message": "User deleted successfully"}
 
-@router.post("/{user_id}/activate")
+@router.post("/{user_id}/activate", summary="激活用户", description="激活指定用户账户（仅管理员）", response_model=UserResponse)
 async def activate_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_admin),
     user_repo: UserRepository = Depends(get_user_repository)
 ) -> UserResponse:
     """
-    激活用户（仅管理员）
+    激活用户
+    
+    激活指定用户的账户（需要管理员权限）
     """
     user_update = UserUpdate(is_active=True)
     updated_user = await user_repo.update_user(user_id, user_update)
@@ -152,14 +158,16 @@ async def activate_user(
     
     return UserResponse.model_validate(updated_user)
 
-@router.post("/{user_id}/deactivate")
+@router.post("/{user_id}/deactivate", summary="停用用户", description="停用指定用户账户（仅管理员）", response_model=UserResponse)
 async def deactivate_user(
-    user_id: int,
+    user_id: int = Path(..., gt=0, description="用户ID"),
     current_user: UserInDB = Depends(get_current_admin),
     user_repo: UserRepository = Depends(get_user_repository)
 ) -> UserResponse:
     """
-    停用用户（仅管理员）
+    停用用户
+    
+    停用指定用户的账户（需要管理员权限，不能停用自己）
     """
     # 不能停用自己
     if current_user.id == user_id: