feat: restore x-ai-description entries in OpenAPI schema (#16502)

feat: inject x-ai-description from overlay file during schema generation

Many endpoints have human-readable AI descriptions that were added
downstream in aap-mcp-server (PRs #73 and #119) but never backported
as @extend_schema_if_available decorators. This causes 470 out of 631
x-ai-description entries to be lost every time the spec is regenerated.

Add a JSON overlay file (openapi_ai_descriptions.json) containing the
missing descriptions keyed by operationId, and a drf-spectacular
postprocessing hook that merges them into the generated schema for any
operation that doesn't already have x-ai-description from a decorator.

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

awx/api/schema.py

@@ -1,3 +1,5 @@
+import json
+import os
 import warnings
 
 from rest_framework.permissions import IsAuthenticated
@@ -53,6 +55,37 @@ def filter_credential_type_schema(
     return result
 
 
+def inject_ai_descriptions(
+    result,
+    generator,  # NOSONAR
+    request,  # NOSONAR
+    public,  # NOSONAR
+):
+    """
+    Inject x-ai-description into operations from the overlay file.
+
+    Many endpoints have human-readable AI descriptions that were added
+    downstream but not backported as @extend_schema_if_available decorators.
+    This hook merges them from a JSON file keyed by operationId.
+    """
+    overlay_path = os.path.join(os.path.dirname(__file__), 'openapi_ai_descriptions.json')
+    try:
+        with open(overlay_path) as f:
+            descriptions = json.load(f)
+    except (FileNotFoundError, json.JSONDecodeError):
+        return result
+
+    for path_item in result.get('paths', {}).values():
+        for operation in path_item.values():
+            if not isinstance(operation, dict):
+                continue
+            op_id = operation.get('operationId')
+            if op_id and op_id in descriptions and 'x-ai-description' not in operation:
+                operation['x-ai-description'] = descriptions[op_id]
+
+    return result
+
+
 class CustomAutoSchema(AutoSchema):
     """Custom AutoSchema to add swagger_topic to tags and handle deprecated endpoints."""