Api docs updates (#20388)

* Update classification API docs

* Add information to events api

* Fix tag

* Add exports

* Add generic response to model for classification apis

* Add preview API information

* Cleanup

* Cleanup

frigate/api/preview.py

@@ -9,6 +9,10 @@ from fastapi import APIRouter, Depends
 from fastapi.responses import JSONResponse
 
 from frigate.api.auth import require_camera_access
+from frigate.api.defs.response.preview_response import (
+    PreviewFramesResponse,
+    PreviewsResponse,
+)
 from frigate.api.defs.tags import Tags
 from frigate.const import BASE_DIR, CACHE_DIR, PREVIEW_FRAME_TYPE
 from frigate.models import Previews
@@ -21,7 +25,13 @@ router = APIRouter(tags=[Tags.preview])
 
 @router.get(
     "/preview/{camera_name}/start/{start_ts}/end/{end_ts}",
+    response_model=PreviewsResponse,
     dependencies=[Depends(require_camera_access)],
+    summary="Get preview clips for time range",
+    description="""Gets all preview clips for a specified camera and time range.
+    Returns a list of preview video clips that overlap with the requested time period,
+    ordered by start time. Use camera_name='all' to get previews from all cameras.
+    Returns an error if no previews are found.""",
 )
 def preview_ts(camera_name: str, start_ts: float, end_ts: float):
     """Get all mp4 previews relevant for time period."""
@@ -77,7 +87,13 @@ def preview_ts(camera_name: str, start_ts: float, end_ts: float):
 
 @router.get(
     "/preview/{year_month}/{day}/{hour}/{camera_name}/{tz_name}",
+    response_model=PreviewsResponse,
     dependencies=[Depends(require_camera_access)],
+    summary="Get preview clips for specific hour",
+    description="""Gets all preview clips for a specific hour in a given timezone.
+    Converts the provided date/time from the specified timezone to UTC and retrieves
+    all preview clips for that hour. Use camera_name='all' to get previews from all cameras.
+    The tz_name should be a timezone like 'America/New_York' (use commas instead of slashes).""",
 )
 def preview_hour(year_month: str, day: int, hour: int, camera_name: str, tz_name: str):
     """Get all mp4 previews relevant for time period given the timezone"""
@@ -95,7 +111,12 @@ def preview_hour(year_month: str, day: int, hour: int, camera_name: str, tz_name
 
 @router.get(
     "/preview/{camera_name}/start/{start_ts}/end/{end_ts}/frames",
+    response_model=PreviewFramesResponse,
     dependencies=[Depends(require_camera_access)],
+    summary="Get cached preview frame filenames",
+    description="""Gets a list of cached preview frame filenames for a specific camera and time range.
+    Returns an array of filenames for preview frames that fall within the specified time period,
+    sorted in chronological order. These are individual frame images cached for quick preview display.""",
 )
 def get_preview_frames_from_cache(camera_name: str, start_ts: float, end_ts: float):
     """Get list of cached preview frames"""