From acf8721a09bb1a3ddb35edd16e9689ca950639dc Mon Sep 17 00:00:00 2001 From: Rodrigo Toshiaki Horie Date: Wed, 21 Jan 2026 16:53:19 -0300 Subject: [PATCH] Enhance OpenAPI schema with AI descriptions and fix method names (#16228) * Enhance OpenAPI schema with AI descriptions and fix method names Add x-ai-description extensions to API endpoints for better AI agent comprehension. Fix view method names to ensure proper drf-spectacular schema generation. * Enhance OpenAPI schema with AI descriptions and fix method names Add x-ai-description extensions to API endpoints for better AI agent comprehension. Fix view method names to ensure proper drf-spectacular schema generation. --- awx/api/views/__init__.py | 152 +++++++++++++++++++++++++++++++++---- awx/api/views/analytics.py | 4 +- awx/api/views/inventory.py | 4 + awx/api/views/root.py | 4 +- awx/conf/views.py | 9 +++ 5 files changed, 153 insertions(+), 20 deletions(-) diff --git a/awx/api/views/__init__.py b/awx/api/views/__init__.py index f2a65cb2ba..084741e699 100644 --- a/awx/api/views/__init__.py +++ b/awx/api/views/__init__.py @@ -385,6 +385,14 @@ class InstanceList(ListCreateAPIView): ordering = ('id',) resource_purpose = 'instances' + @extend_schema_if_available( + extensions={ + "x-ai-description": "Register an execution or hop node instance. Only available on openshift based AAP deployments. Use the install bundle playbook to further provision the instance" + } + ) + def post(self, request, *args, **kwargs): + return super().post(request, *args, **kwargs) + def get_queryset(self): qs = super().get_queryset().prefetch_related('receptor_addresses') return qs @@ -539,6 +547,14 @@ class InstanceGroupList(ListCreateAPIView): serializer_class = serializers.InstanceGroupSerializer resource_purpose = 'instance groups' + @extend_schema_if_available(extensions={"x-ai-description": "A list of instance groups."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Create an instance group. Instances in this group determine where a job will be executed"}) + def post(self, request, *args, **kwargs): + return super().post(request, *args, **kwargs) + class InstanceGroupDetail(RelatedJobsPreventDeleteMixin, RetrieveUpdateDestroyAPIView): always_allow_superuser = False @@ -868,6 +884,14 @@ class ExecutionEnvironmentList(ListCreateAPIView): swagger_topic = "Execution Environments" resource_purpose = 'execution environments' + @extend_schema_if_available(extensions={"x-ai-description": "A list of execution environments."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Create a new execution environment. Once associated with JT/org/etc"}) + def post(self, request, *args, **kwargs): + return super().post(request, *args, **kwargs) + class ExecutionEnvironmentDetail(RetrieveUpdateDestroyAPIView): always_allow_superuser = False @@ -891,6 +915,22 @@ class ExecutionEnvironmentDetail(RetrieveUpdateDestroyAPIView): raise PermissionDenied(_("Only the 'pull' field can be edited for managed execution environments.")) return super().update(request, *args, **kwargs) + @extend_schema_if_available( + extensions={"x-ai-description": "Update all fields of an execution environment. All fields must be provided in the request body."} + ) + def put(self, request, *args, **kwargs): + return super().put(request, *args, **kwargs) + + @extend_schema_if_available( + extensions={"x-ai-description": "Update specific fields of an execution environment. Only the fields you provide will be updated."} + ) + def patch(self, request, *args, **kwargs): + return super().patch(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Delete an execution environment."}) + def delete(self, request, *args, **kwargs): + return super().delete(request, *args, **kwargs) + class ExecutionEnvironmentJobTemplateList(SubListAPIView): model = models.UnifiedJobTemplate @@ -921,6 +961,10 @@ class ProjectList(ListCreateAPIView): serializer_class = serializers.ProjectSerializer resource_purpose = 'projects' + @extend_schema_if_available(extensions={"x-ai-description": "A list of projects."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + class ProjectDetail(RelatedJobsPreventDeleteMixin, RetrieveUpdateDestroyAPIView): model = models.Project @@ -1346,12 +1390,28 @@ class CredentialTypeList(ListCreateAPIView): serializer_class = serializers.CredentialTypeSerializer resource_purpose = 'credential types' + @extend_schema_if_available(extensions={"x-ai-description": "A list of credential types"}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Create a new custom credential type"}) + def post(self, request, *args, **kwargs): + return super().post(request, *args, **kwargs) + class CredentialTypeDetail(RetrieveUpdateDestroyAPIView): model = models.CredentialType serializer_class = serializers.CredentialTypeSerializer resource_purpose = 'credential type detail' + @extend_schema_if_available(extensions={"x-ai-description": "Update a custom credential type."}) + def put(self, request, *args, **kwargs): + return super().put(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Update a custom credential type."}) + def patch(self, request, *args, **kwargs): + return super().patch(request, *args, **kwargs) + def destroy(self, request, *args, **kwargs): instance = self.get_object() if instance.managed: @@ -1360,6 +1420,10 @@ class CredentialTypeDetail(RetrieveUpdateDestroyAPIView): raise PermissionDenied(detail=_("Credential types that are in use cannot be deleted")) return super(CredentialTypeDetail, self).destroy(request, *args, **kwargs) + @extend_schema_if_available(extensions={"x-ai-description": "Delete a custom credential type. Cannot delete managed types or types currently in use."}) + def delete(self, request, *args, **kwargs): + return super().delete(request, *args, **kwargs) + class CredentialTypeCredentialList(SubListCreateAPIView): model = models.Credential @@ -1384,6 +1448,10 @@ class CredentialList(ListCreateAPIView): serializer_class = serializers.CredentialSerializerCreate resource_purpose = 'credentials' + @extend_schema_if_available(extensions={"x-ai-description": "A list of credentials"}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + @extend_schema_if_available( extensions={ "x-ai-description": "Create a new credential. The `inputs` field contain type-specific input fields. The required fields depend on related `credential_type`. Use GET /v2/credential_types/{id}/ (tool name: controller.credential_types_retrieve) and inspect `inputs` field for the specific credential type's expected schema." @@ -1673,6 +1741,10 @@ class HostList(HostRelatedSearchMixin, ListCreateAPIView): serializer_class = serializers.HostSerializer resource_purpose = 'hosts' + @extend_schema_if_available(extensions={"x-ai-description": "A list of hosts."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + def get_queryset(self): qs = super(HostList, self).get_queryset() filter_string = self.request.query_params.get('host_filter', None) @@ -1816,6 +1888,14 @@ class GroupList(ListCreateAPIView): serializer_class = serializers.GroupSerializer resource_purpose = 'groups' + @extend_schema_if_available(extensions={"x-ai-description": "A list of groups."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Create a new group."}) + def post(self, request, *args, **kwargs): + return super().post(request, *args, **kwargs) + class EnforceParentRelationshipMixin(object): """ @@ -2015,6 +2095,10 @@ class HostVariableData(BaseVariableData): serializer_class = serializers.HostVariableDataSerializer resource_purpose = 'variable data for a host' + @extend_schema_if_available(extensions={"x-ai-description": "The extra variable configuration for this host."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + class GroupVariableData(BaseVariableData): model = models.Group @@ -2302,7 +2386,7 @@ class InventorySourceUpdateView(RetrieveAPIView): serializer_class = serializers.InventorySourceUpdateSerializer resource_purpose = 'update an inventory source' - @extend_schema_if_available(extensions={"x-ai-description": "Update inventory source"}) + @extend_schema_if_available(extensions={"x-ai-description": "Sync the inventory source"}) def post(self, request, *args, **kwargs): obj = self.get_object() serializer = self.get_serializer(instance=obj, data=request.data) @@ -2362,6 +2446,10 @@ class JobTemplateList(ListCreateAPIView): always_allow_superuser = False resource_purpose = 'job templates' + @extend_schema_if_available(extensions={"x-ai-description": "A list of job templates."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + def check_permissions(self, request): if request.method == 'POST': if request.user.is_anonymous: @@ -2439,9 +2527,7 @@ class JobTemplateLaunch(RetrieveAPIView): return modern_data - @extend_schema_if_available( - extensions={'x-ai-description': 'Launch a job'}, - ) + @extend_schema_if_available(extensions={"x-ai-description": "Launch the job template"}) def post(self, request, *args, **kwargs): obj = self.get_object() @@ -3140,6 +3226,10 @@ class WorkflowJobTemplateList(ListCreateAPIView): always_allow_superuser = False resource_purpose = 'workflow job templates' + @extend_schema_if_available(extensions={"x-ai-description": "A list of workflow job templates."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + def check_permissions(self, request): if request.method == 'POST': if request.user.is_anonymous: @@ -3253,9 +3343,7 @@ class WorkflowJobTemplateLaunch(RetrieveAPIView): return data - @extend_schema_if_available( - extensions={'x-ai-description': 'Launch a workflow job'}, - ) + @extend_schema_if_available(extensions={"x-ai-description": "Launch the workflow job template."}) def post(self, request, *args, **kwargs): obj = self.get_object() @@ -3297,9 +3385,7 @@ class WorkflowJobRelaunch(GenericAPIView): def get(self, request, *args, **kwargs): return Response({}) - @extend_schema_if_available( - extensions={'x-ai-description': 'Relaunch a workflow job'}, - ) + @extend_schema_if_available(extensions={"x-ai-description": "Relaunch a workflow job"}) def post(self, request, *args, **kwargs): obj = self.get_object() if obj.is_sliced_job: @@ -3416,6 +3502,10 @@ class WorkflowJobList(ListAPIView): serializer_class = serializers.WorkflowJobListSerializer resource_purpose = 'workflow jobs' + @extend_schema_if_available(extensions={"x-ai-description": "A list of workflow jobs."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + class WorkflowJobDetail(UnifiedJobDeletionMixin, RetrieveDestroyAPIView): model = models.WorkflowJob @@ -3441,7 +3531,7 @@ class WorkflowJobCancel(GenericCancelView): serializer_class = serializers.WorkflowJobCancelSerializer resource_purpose = 'cancel for a workflow job' - @extend_schema_if_available(extensions={"x-ai-description": "Cancel a workflow job"}) + @extend_schema_if_available(extensions={"x-ai-description": "Cancel a running or pending workflow job"}) def post(self, request, *args, **kwargs): r = super().post(request, *args, **kwargs) ScheduleWorkflowManager().schedule() @@ -3562,6 +3652,10 @@ class JobList(ListAPIView): serializer_class = serializers.JobListSerializer resource_purpose = 'jobs' + @extend_schema_if_available(extensions={"x-ai-description": "A list of jobs."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + class JobDetail(UnifiedJobDeletionMixin, RetrieveDestroyAPIView): model = models.Job @@ -3611,6 +3705,10 @@ class JobCancel(GenericCancelView): serializer_class = serializers.JobCancelSerializer resource_purpose = 'cancel for a job' + @extend_schema_if_available(extensions={"x-ai-description": "Cancel a running or pending job"}) + def post(self, request, *args, **kwargs): + return super().post(request, *args, **kwargs) + class JobRelaunch(RetrieveAPIView): model = models.Job @@ -3645,9 +3743,7 @@ class JobRelaunch(RetrieveAPIView): self.permission_denied(request, message=messages['detail']) return super(JobRelaunch, self).check_object_permissions(request, obj) - @extend_schema_if_available( - extensions={'x-ai-description': 'Relaunch a job'}, - ) + @extend_schema_if_available(extensions={"x-ai-description": "Relaunch a job"}) def post(self, request, *args, **kwargs): obj = self.get_object() context = self.get_serializer_context() @@ -4397,6 +4493,10 @@ class JobStdout(UnifiedJobStdout): model = models.Job resource_purpose = 'stdout output of a job' + @extend_schema_if_available(extensions={"x-ai-description": "Get the standard output for the selected job."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + class AdHocCommandStdout(UnifiedJobStdout): model = models.AdHocCommand @@ -4408,12 +4508,28 @@ class NotificationTemplateList(ListCreateAPIView): serializer_class = serializers.NotificationTemplateSerializer resource_purpose = 'notification templates' + @extend_schema_if_available(extensions={"x-ai-description": "A list of notification templates."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Create a new notification template."}) + def post(self, request, *args, **kwargs): + return super().post(request, *args, **kwargs) + class NotificationTemplateDetail(RetrieveUpdateDestroyAPIView): model = models.NotificationTemplate serializer_class = serializers.NotificationTemplateSerializer resource_purpose = 'notification template detail' + @extend_schema_if_available(extensions={"x-ai-description": "Update a notification template."}) + def put(self, request, *args, **kwargs): + return super().put(request, *args, **kwargs) + + @extend_schema_if_available(extensions={"x-ai-description": "Update a notification template."}) + def patch(self, request, *args, **kwargs): + return super().patch(request, *args, **kwargs) + @extend_schema_if_available(extensions={"x-ai-description": "Delete a notification template"}) def delete(self, request, *args, **kwargs): obj = self.get_object() @@ -4493,6 +4609,14 @@ class ActivityStreamList(SimpleListAPIView): search_fields = ('changes',) resource_purpose = 'audit trail entries for tracking system changes' + @extend_schema_if_available( + extensions={ + "x-ai-description": "A list of activity stream entries. An activity stream entry tracks actions or changes that were previously made to the system." + } + ) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + class ActivityStreamDetail(RetrieveAPIView): model = models.ActivityStream diff --git a/awx/api/views/analytics.py b/awx/api/views/analytics.py index 8019f40e9e..6a855eab70 100644 --- a/awx/api/views/analytics.py +++ b/awx/api/views/analytics.py @@ -52,9 +52,7 @@ class AnalyticsRootView(APIView): swagger_topic = 'Automation Analytics' resource_purpose = 'automation analytics endpoints' - @extend_schema_if_available( - extensions={'x-ai-description': 'Retrieve list of available analytics endpoints'}, - ) + @extend_schema_if_available(extensions={"x-ai-description": "A list of additional API endpoints related to analytics"}) def get(self, request, format=None): data = OrderedDict() data['authorized'] = reverse('api:analytics_authorized', request=request) diff --git a/awx/api/views/inventory.py b/awx/api/views/inventory.py index e518c74963..8be0a2f630 100644 --- a/awx/api/views/inventory.py +++ b/awx/api/views/inventory.py @@ -73,6 +73,10 @@ class InventoryList(ListCreateAPIView): serializer_class = InventorySerializer resource_purpose = 'inventories' + @extend_schema_if_available(extensions={"x-ai-description": "A list of inventories."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + class InventoryDetail(RelatedJobsPreventDeleteMixin, RetrieveUpdateDestroyAPIView): model = Inventory diff --git a/awx/api/views/root.py b/awx/api/views/root.py index f05e36d70b..506cdcf8d5 100644 --- a/awx/api/views/root.py +++ b/awx/api/views/root.py @@ -366,9 +366,7 @@ class ApiV2ConfigView(APIView): return Response(data) - @extend_schema_if_available( - extensions={'x-ai-description': 'Upload a subscription manifest'}, - ) + @extend_schema_if_available(extensions={"x-ai-description": "Add or update a subscription manifest license"}) def post(self, request): if not isinstance(request.data, dict): return Response({"error": _("Invalid subscription data")}, status=status.HTTP_400_BAD_REQUEST) diff --git a/awx/conf/views.py b/awx/conf/views.py index 6b4345a1b1..b38c9c5e14 100644 --- a/awx/conf/views.py +++ b/awx/conf/views.py @@ -31,6 +31,7 @@ from awx.conf.models import Setting from awx.conf.serializers import SettingCategorySerializer, SettingSingletonSerializer from awx.conf import settings_registry from awx.main.utils.external_logging import reconfigure_rsyslog +from ansible_base.lib.utils.schema import extend_schema_if_available SettingCategory = collections.namedtuple('SettingCategory', ('url', 'slug', 'name')) @@ -41,6 +42,10 @@ class SettingCategoryList(ListAPIView): filter_backends = [] name = _('Setting Categories') + @extend_schema_if_available(extensions={"x-ai-description": "A list of additional API endpoints related to settings."}) + def get(self, request, *args, **kwargs): + return super().get(request, *args, **kwargs) + def get_queryset(self): setting_categories = [] categories = settings_registry.get_registered_categories() @@ -62,6 +67,10 @@ class SettingSingletonDetail(RetrieveUpdateDestroyAPIView): filter_backends = [] name = _('Setting Detail') + @extend_schema_if_available(extensions={"x-ai-description": "Update system settings."}) + def patch(self, request, *args, **kwargs): + return super().patch(request, *args, **kwargs) + def get_queryset(self): self.category_slug = self.kwargs.get('category_slug', 'all') all_category_slugs = list(settings_registry.get_registered_categories().keys())