Phase 5.14: API documentation - OpenAPI tags, response models, examples, docs

app/routes/users.py

@@ -14,7 +14,7 @@ from app.core.db import get_db
 from app.core.notifications import create_notification
 from app.core.permissions import invalidate_permission_cache
 from app.deps import require_permission
-from app.schemas.user import UserCreate, UserUpdate
+from app.schemas.user import UserCreate, UserUpdate, UserResponse, PaginatedUsers
 from app.services.user_service import user_service, _UNSET
 
 router = APIRouter(prefix="/api/v1/users", tags=["users"])
@@ -36,7 +36,7 @@ def _parse_role_id(raw: str | None) -> uuid.UUID | None:
         ) from None
 
 
-@router.get("")
+@router.get("", response_model=PaginatedUsers)
 async def list_users(
     page: int = Query(1, ge=1),
     page_size: int = Query(25, ge=1, le=100),
@@ -49,7 +49,7 @@ async def list_users(
     return await user_service.list_users(db, tenant_id, page, page_size, search)
 
 
-@router.post("", status_code=status.HTTP_201_CREATED)
+@router.post("", status_code=status.HTTP_201_CREATED, response_model=UserResponse)
 async def create_user(
     body: UserCreate,
     db: AsyncSession = Depends(get_db),
@@ -103,7 +103,7 @@ async def create_user(
     }
 
 
-@router.get("/{user_id}")
+@router.get("/{user_id}", response_model=UserResponse)
 async def get_user(
     user_id: str,
     db: AsyncSession = Depends(get_db),