docs: Add detailed docstrings to API models and update OpenAPI spec (#2889)

This PR focuses on improving the developer experience by adding
comprehensive docstrings to the API data models across the Llama Stack.
These docstrings provide detailed explanations for each model and its
fields, making the API easier to understand and use.

**Key changes:**
- **Added Docstrings:** Added reST formatted docstrings to Pydantic
models in the `llama_stack/apis/` directory. This includes models for:
  - Agents (`agents.py`)
  - Benchmarks (`benchmarks.py`)
  - Datasets (`datasets.py`)
  - Inference (`inference.py`)
  - And many other API modules.
- **OpenAPI Spec Update:** Regenerated the OpenAPI specification
(`docs/_static/llama-stack-spec.yaml` and
`docs/_static/llama-stack-spec.html`) to include the new docstrings.
This will be reflected in the API documentation, providing richer
information to users.

**Impact:**
- Developers using the Llama Stack API will have a better understanding
of the data structures.
- The auto-generated API documentation is now more informative.

---------

Co-authored-by: Ashwin Bharambe <ashwin.bharambe@gmail.com>

llama_stack/apis/inspect/inspect.py

@@ -14,6 +14,13 @@ from llama_stack.schema_utils import json_schema_type, webmethod
 
 @json_schema_type
 class RouteInfo(BaseModel):
+    """Information about an API route including its path, method, and implementing providers.
+
+    :param route: The API endpoint path
+    :param method: HTTP method for the route
+    :param provider_types: List of provider types that implement this route
+    """
+
     route: str
     method: str
     provider_types: list[str]
@@ -21,15 +28,30 @@ class RouteInfo(BaseModel):
 
 @json_schema_type
 class HealthInfo(BaseModel):
+    """Health status information for the service.
+
+    :param status: Current health status of the service
+    """
+
     status: HealthStatus
 
 
 @json_schema_type
 class VersionInfo(BaseModel):
+    """Version information for the service.
+
+    :param version: Version number of the service
+    """
+
     version: str
 
 
 class ListRoutesResponse(BaseModel):
+    """Response containing a list of all available API routes.
+
+    :param data: List of available route information objects
+    """
+
     data: list[RouteInfo]
 
 
@@ -37,17 +59,17 @@ class ListRoutesResponse(BaseModel):
 class Inspect(Protocol):
     @webmethod(route="/inspect/routes", method="GET")
     async def list_routes(self) -> ListRoutesResponse:
-        """List all routes.
+        """List all available API routes with their methods and implementing providers.
 
-        :returns: A ListRoutesResponse.
+        :returns: Response containing information about all available routes.
         """
         ...
 
     @webmethod(route="/health", method="GET")
     async def health(self) -> HealthInfo:
-        """Get the health of the service.
+        """Get the current health status of the service.
 
-        :returns: A HealthInfo.
+        :returns: Health information indicating if the service is operational.
         """
         ...
 
@@ -55,6 +77,6 @@ class Inspect(Protocol):
     async def version(self) -> VersionInfo:
         """Get the version of the service.
 
-        :returns: A VersionInfo.
+        :returns: Version information containing the service version number.
         """
         ...