docs: api separation

docs/openapi_generator/pyopenapi/generator.py

@@ -7,13 +7,14 @@
 import hashlib
 import inspect
 import ipaddress
+import os
 import types
 import typing
 from dataclasses import make_dataclass
+from pathlib import Path
 from typing import Annotated, Any, Dict, get_args, get_origin, Set, Union
 
 from fastapi import UploadFile
-from pydantic import BaseModel
 
 from llama_stack.apis.datatypes import Error
 from llama_stack.strong_typing.core import JsonType
@@ -35,6 +36,7 @@ from llama_stack.strong_typing.schema import (
     SchemaOptions,
 )
 from llama_stack.strong_typing.serialization import json_dump_string, object_to_json
+from pydantic import BaseModel
 
 from .operations import (
     EndpointOperation,
@@ -811,16 +813,121 @@ class Generator:
             requestBody=requestBody,
             responses=responses,
             callbacks=callbacks,
-            deprecated=True if "DEPRECATED" in op.func_name else None,
+            deprecated=getattr(op.webmethod, "deprecated", False)
+            or "DEPRECATED" in op.func_name,
             security=[] if op.public else None,
         )
 
+    def _get_api_stability_priority(self, api_level: str) -> int:
+        """
+        Return sorting priority for API stability levels.
+        Lower numbers = higher priority (appear first)
+
+        :param api_level: The API level (e.g., "v1", "v1beta", "v1alpha")
+        :return: Priority number for sorting
+        """
+        stability_order = {
+            "v1": 0,  # Stable - highest priority
+            "v1beta": 1,  # Beta - medium priority
+            "v1alpha": 2,  # Alpha - lowest priority
+        }
+        return stability_order.get(api_level, 999)  # Unknown levels go last
+
     def generate(self) -> Document:
         paths: Dict[str, PathItem] = {}
         endpoint_classes: Set[type] = set()
-        for op in get_endpoint_operations(
-            self.endpoint, use_examples=self.options.use_examples
-        ):
+
+        # Collect all operations and filter by stability if specified
+        operations = list(
+            get_endpoint_operations(
+                self.endpoint, use_examples=self.options.use_examples
+            )
+        )
+
+        # Filter operations by stability level if requested
+        if self.options.stability_filter:
+            filtered_operations = []
+            for op in operations:
+                deprecated = (
+                    getattr(op.webmethod, "deprecated", False)
+                    or "DEPRECATED" in op.func_name
+                )
+                stability_level = op.webmethod.level
+
+                if self.options.stability_filter == "stable":
+                    # Include v1 non-deprecated endpoints
+                    if stability_level == "v1" and not deprecated:
+                        filtered_operations.append(op)
+                elif self.options.stability_filter == "experimental":
+                    # Include v1alpha and v1beta endpoints (deprecated or not)
+                    if stability_level in ["v1alpha", "v1beta"]:
+                        filtered_operations.append(op)
+                elif self.options.stability_filter == "deprecated":
+                    # Include only deprecated endpoints
+                    if deprecated:
+                        filtered_operations.append(op)
+
+            operations = filtered_operations
+            print(
+                f"Filtered to {len(operations)} operations for stability level: {self.options.stability_filter}"
+            )
+
+        # Sort operations by multiple criteria for consistent ordering:
+        # 1. Stability level with deprecation handling (global priority):
+        #    - Active stable (v1) comes first
+        #    - Beta (v1beta) comes next
+        #    - Alpha (v1alpha) comes next
+        #    - Deprecated stable (v1 deprecated) comes last
+        # 2. Route path (group related endpoints within same stability level)
+        # 3. HTTP method (GET, POST, PUT, DELETE, PATCH)
+        # 4. Operation name (alphabetical)
+        def sort_key(op):
+            http_method_order = {
+                HTTPMethod.GET: 0,
+                HTTPMethod.POST: 1,
+                HTTPMethod.PUT: 2,
+                HTTPMethod.DELETE: 3,
+                HTTPMethod.PATCH: 4,
+            }
+
+            # Enhanced stability priority for migration pattern support
+            deprecated = getattr(op.webmethod, "deprecated", False)
+            stability_priority = self._get_api_stability_priority(op.webmethod.level)
+
+            # Deprecated versions should appear after everything else
+            # This ensures deprecated stable endpoints come last globally
+            if deprecated:
+                stability_priority += 10  # Push deprecated endpoints to the end
+
+            return (
+                stability_priority,  # Global stability handling comes first
+                op.get_route(
+                    op.webmethod
+                ),  # Group by route path within stability level
+                http_method_order.get(op.http_method, 999),
+                op.func_name,
+            )
+
+        operations.sort(key=sort_key)
+
+        # Debug output for migration pattern tracking
+        migration_routes = {}
+        for op in operations:
+            route_key = (op.get_route(op.webmethod), op.http_method)
+            if route_key not in migration_routes:
+                migration_routes[route_key] = []
+            migration_routes[route_key].append(
+                (op.webmethod.level, getattr(op.webmethod, "deprecated", False))
+            )
+
+        for route_key, versions in migration_routes.items():
+            if len(versions) > 1:
+                print(f"Migration pattern detected for {route_key[1]} {route_key[0]}:")
+                for level, deprecated in versions:
+                    status = "DEPRECATED" if deprecated else "ACTIVE"
+                    print(f"  - {level} ({status})")
+
+        for op in operations:
             endpoint_classes.add(op.defining_class)
 
             operation = self._build_operation(op)
@@ -851,6 +958,7 @@ class Generator:
             doc_string = parse_type(cls)
             if hasattr(cls, "API_NAMESPACE") and cls.API_NAMESPACE != cls.__name__:
                 continue
+
             operation_tags.append(
                 Tag(
                     name=cls.__name__,