External-Mirrors/awx
2
0
Fork 0
mirror of https://github.com/ansible/awx.git synced 2026-02-02 01:58:09 -03:30
Code Issues Packages Projects Releases Wiki Activity

Enhance OpenAPI schema with AI descriptions and fix method names (#16228)

Browse Source 
* 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.
This commit is contained in:
Rodrigo Toshiaki Horie
2026-01-21 16:53:19 -03:00
committed by GitHub
parent a839ce8cb1
commit acf8721a09
5 changed files with 153 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
awx/api/views/__init__.py
View File

@@ -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

4
awx/api/views/analytics.py
View File

@@ -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)

4
awx/api/views/inventory.py
View File

@@ -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

4
awx/api/views/root.py
View File

@@ -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)

9
awx/conf/views.py
View File

@@ -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())