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

app/routes/auth.py

@@ -12,7 +12,9 @@ from app.core.auth import get_redis
 from app.core.db import get_db
 from app.core.rate_limit import check_rate_limit, get_client_ip, reset_rate_limit
 from app.schemas.auth import (
+    AuthResponse,
     LoginRequest,
+    MessageResponse,
     PasswordResetConfirm,
     PasswordResetRequest,
     SwitchTenantRequest,
@@ -24,7 +26,7 @@ router = APIRouter(prefix="/api/v1/auth", tags=["auth"])
 settings = get_settings()
 
 
-@router.post("/login")
+@router.post("/login", response_model=AuthResponse)
 async def login(
     request: Request,
     body: LoginRequest,
@@ -91,7 +93,7 @@ async def login(
     return resp
 
 
-@router.post("/logout")
+@router.post("/logout", response_model=MessageResponse)
 async def logout(
     request: Request,
     db: AsyncSession = Depends(get_db),
@@ -112,7 +114,7 @@ async def logout(
     return resp
 
 
-@router.get("/me")
+@router.get("/me", response_model=AuthResponse)
 async def me(
     request: Request,
     db: AsyncSession = Depends(get_db),

app/routes/health.py

@@ -5,11 +5,12 @@ from __future__ import annotations
 from fastapi import APIRouter
 
 from app.core.monitoring import get_health_status
+from app.schemas.common import HealthResponse
 
 router = APIRouter(tags=["health"])
 
 
-@router.get("/api/v1/health")
+@router.get("/api/v1/health", response_model=HealthResponse)
 async def health():
     """Health check — no auth required.
 

app/routes/notifications.py

@@ -19,7 +19,7 @@ from app.models.notification import (
     NotificationPreference,
     NotificationType,
 )
-from app.schemas.common import NotificationPreferenceUpdate
+from app.schemas.common import NotificationPreferenceUpdate, UnreadCountResponse
 
 router = APIRouter(prefix="/api/v1/notifications", tags=["notifications"])
 
@@ -67,7 +67,7 @@ async def mark_notification_read_endpoint(
     }
 
 
-@router.get("/unread-count")
+@router.get("/unread-count", response_model=UnreadCountResponse)
 async def unread_count_endpoint(
     db: AsyncSession = Depends(get_db),
     current_user: dict = Depends(require_permission("notifications:read")),

app/routes/system_settings.py

@@ -9,13 +9,13 @@ from sqlalchemy.ext.asyncio import AsyncSession
 
 from app.core.db import get_db
 from app.deps import require_permission
-from app.schemas.system_settings import SystemSettingsUpsert
+from app.schemas.system_settings import SystemSettingsUpsert, SystemSettingsResponse
 from app.services import system_settings_service
 
 router = APIRouter(prefix="/api/v1/system-settings", tags=["system-settings"])
 
 
-@router.get("")
+@router.get("", response_model=SystemSettingsResponse)
 async def get_system_settings(
     db: AsyncSession = Depends(get_db),
     current_user: dict = Depends(require_permission("settings:read")),
@@ -28,7 +28,7 @@ async def get_system_settings(
     return result
 
 
-@router.put("")
+@router.put("", response_model=SystemSettingsResponse)
 async def upsert_system_settings(
     body: SystemSettingsUpsert,
     db: AsyncSession = Depends(get_db),

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),