diff --git a/awx/api/openapi_ai_descriptions.json b/awx/api/openapi_ai_descriptions.json index c970e61e76..6af09d7716 100644 --- a/awx/api/openapi_ai_descriptions.json +++ b/awx/api/openapi_ai_descriptions.json @@ -1,10 +1,10 @@ { "activity_stream_retrieve": "Retrieve an audit trail entry for tracking all changes within the system", "ad_hoc_commands_activity_stream_list": "List activity stream of an ad hoc command", - "ad_hoc_commands_create": "Create an ad hoc command", + "ad_hoc_commands_create": "Run an ad hoc command. Executes a single Ansible module on specified hosts without a playbook.", "ad_hoc_commands_destroy": "Delete an ad hoc command", "ad_hoc_commands_events_list": "List events of an ad hoc command", - "ad_hoc_commands_list": "List ad hoc commands", + "ad_hoc_commands_list": "Returns a paginated list of all ad hoc command runs. Ad hoc commands execute a single Ansible module without a playbook.", "ad_hoc_commands_notifications_list": "List notifications of an ad hoc command", "ad_hoc_commands_retrieve": "Retrieve an ad hoc command", "ad_hoc_commands_stdout_retrieve": "Retrieve a stdout output of an ad hoc command", @@ -30,7 +30,7 @@ "constructed_inventories_update": "Update a constructed inventory", "credential_input_sources_create": "Create a credential input source", "credential_input_sources_destroy": "Delete a credential input source", - "credential_input_sources_list": "List credential input sources", + "credential_input_sources_list": "Returns a paginated list of external secret management input sources.", "credential_input_sources_partial_update": "Update a credential input source", "credential_input_sources_retrieve": "Retrieve a credential input source", "credential_input_sources_update": "Update a credential input source", @@ -39,7 +39,7 @@ "credential_types_retrieve": "Retrieve a credential type", "credential_types_test_retrieve": "Retrieve single test for a credential_type", "credentials_destroy": "Delete a credential", - "credentials_input_sources_create": "Create new source for a credential", + "credentials_input_sources_create": "Link an external secret source (Vault, CyberArk) to a credential field.", "credentials_input_sources_list": "List all sources for a credential", "credentials_object_roles_list": "List roles of a credential", "credentials_owner_teams_list": "List all teams for a credential", @@ -57,7 +57,7 @@ "feature_flags_states_list": "List all feature flags states", "feature_flags_states_retrieve": "Retrieve single feature flags state", "groups_activity_stream_list": "List activity stream for a group", - "groups_ad_hoc_commands_create": "Create an ad hoc command for a group", + "groups_ad_hoc_commands_create": "Run an ad hoc command against all hosts in a group. Executes a single Ansible module without a playbook.", "groups_ad_hoc_commands_list": "List ad hoc commands for a group", "groups_all_hosts_list": "List all hosts for a group", "groups_children_create": "Create new child for a group", @@ -80,10 +80,10 @@ "host_metrics_retrieve": "Retrieve a host metric", "hosts_activity_stream_list": "List activity stream for a host", "hosts_ad_hoc_command_events_list": "List events of ad hoc command of a host", - "hosts_ad_hoc_commands_create": "Create an ad hoc command of a host", + "hosts_ad_hoc_commands_create": "Run an ad hoc command against a specific host. Executes a single Ansible module without a playbook.", "hosts_ad_hoc_commands_list": "List ad hoc commands of a host", "hosts_all_groups_list": "List all groups for a host", - "hosts_create": "Create a host", + "hosts_create": "Create a host entry in an inventory. Hosts are managed nodes that Ansible automation can execute against.", "hosts_groups_create": "Create the list of groups a host is directly a member of", "hosts_groups_list": "List the list of groups a host is directly a member of", "hosts_inventory_sources_list": "List inventory sources of a host", @@ -112,11 +112,11 @@ "instances_retrieve": "Retrieve an instance", "instances_update": "Update an instance", "inventories_access_list_list": "List users who can access the inventory", - "inventories_ad_hoc_commands_create": "Create an ad hoc command for an inventory", + "inventories_ad_hoc_commands_create": "Run an ad hoc command against all hosts in an inventory. Executes a single Ansible module without a playbook.", "inventories_ad_hoc_commands_list": "List ad hoc command for an inventory", "inventories_copy_create": "Create a copy of an inventory", "inventories_copy_retrieve": "Retrieve a copy of an inventory", - "inventories_create": "Create an inventory", + "inventories_create": "Create an inventory to define the set of hosts that jobs can target.", "inventories_destroy": "Delete an inventory", "inventories_groups_create": "Create a group of an inventory", "inventories_groups_list": "List groups of an inventory", @@ -137,7 +137,7 @@ "inventories_variable_data_retrieve": "Retrieve single datum for an inventory", "inventories_variable_data_update": "Update existing datum for an inventory", "inventory_sources_activity_stream_list": "List activity stream of an inventory source", - "inventory_sources_create": "Create an inventory source", + "inventory_sources_create": "Create an inventory source to sync host data from external systems.", "inventory_sources_credentials_create": "Create a credential of an inventory source", "inventory_sources_credentials_list": "List credentials of an inventory source", "inventory_sources_destroy": "Delete an inventory source", @@ -172,20 +172,20 @@ "job_templates_activity_stream_list": "List activity stream of a job template", "job_templates_copy_create": "Create a copy a job template", "job_templates_copy_retrieve": "Retrieve a copy a job template", - "job_templates_create": "Create a job template", - "job_templates_credentials_create": "Create a credential of a job template", + "job_templates_create": "Create a new job template. A job template defines the playbook, inventory, credentials, variables, and settings needed to launch an automation job.", + "job_templates_credentials_create": "Associate a credential with a job template. The credential will be used when launching jobs from this template.", "job_templates_credentials_list": "List credentials of a job template", "job_templates_destroy": "Delete a job template", "job_templates_instance_groups_create": "Create an instance group of a job template", "job_templates_instance_groups_list": "List instance groups of a job template", "job_templates_jobs_list": "List jobs of a job template", "job_templates_labels_list": "List labels of a job template", - "job_templates_launch_retrieve": "Retrieve single launch for a job_template", - "job_templates_notification_templates_error_create": "Create a notification templates triggered on job error", + "job_templates_launch_retrieve": "Returns the launch configuration and required fields needed to launch a specific job template by ID.", + "job_templates_notification_templates_error_create": "Attach a notification template to trigger when a job from this template fails.", "job_templates_notification_templates_error_list": "List notification templates triggered on job error", - "job_templates_notification_templates_started_create": "Create a notification templates triggered on job start", + "job_templates_notification_templates_started_create": "Attach a notification template to trigger when a job from this template starts.", "job_templates_notification_templates_started_list": "List notification templates triggered on job start", - "job_templates_notification_templates_success_create": "Create a notification templates triggered on job success", + "job_templates_notification_templates_success_create": "Attach a notification template to trigger when a job from this template succeeds.", "job_templates_notification_templates_success_list": "List notification templates triggered on job success", "job_templates_object_roles_list": "List roles of a job template", "job_templates_partial_update": "Update a job template", @@ -200,11 +200,11 @@ "jobs_create_schedule_retrieve": "Retrieve single schedule for a job", "jobs_credentials_list": "List credentials of a job", "jobs_destroy": "Delete a job", - "jobs_job_events_list": "List job events of a job", - "jobs_job_host_summaries_list": "List job host summaries of a job", + "jobs_job_events_list": "Returns a paginated list of execution events for a specific job run. Use to inspect task-level output.", + "jobs_job_host_summaries_list": "Returns a paginated list of per-host result summaries (ok, changed, failed counts) for a specific job.", "jobs_labels_list": "List labels of a job", "jobs_notifications_list": "List notifications of a job", - "jobs_relaunch_retrieve": "Retrieve single relaunch for a job", + "jobs_relaunch_retrieve": "Returns the list of credential passwords required to relaunch a specific job by ID.", "jobs_retrieve": "Retrieve a job", "labels_create": "Create a label", "labels_list": "List labels", @@ -226,11 +226,11 @@ "organizations_credentials_create": "Create a credential of an organization", "organizations_credentials_list": "List credentials of an organization", "organizations_destroy": "Delete an organization", - "organizations_execution_environments_create": "Create an execution environment of an organization", + "organizations_execution_environments_create": "Associate an execution environment with an organization by default.", "organizations_execution_environments_list": "List execution environments of an organization", - "organizations_galaxy_credentials_create": "Create new credential for an organization", + "organizations_galaxy_credentials_create": "Associate a Galaxy credential with an organization for syncing content.", "organizations_galaxy_credentials_list": "List all credentials for an organization", - "organizations_instance_groups_create": "Create an instance group of an organization", + "organizations_instance_groups_create": "Associate an instance group with an organization.", "organizations_instance_groups_list": "List instance groups of an organization", "organizations_inventories_list": "List inventories of an organization", "organizations_job_templates_create": "Create a job template of an organization", @@ -271,7 +271,7 @@ "projects_activity_stream_list": "List activity stream for a project", "projects_copy_create": "Create a copy of a project", "projects_copy_retrieve": "Retrieve a copy of a project", - "projects_create": "Create a project", + "projects_create": "Create a new project. Projects represent a collection of Ansible playbooks and related files sourced from a version control system.", "projects_destroy": "Delete a project", "projects_inventories_retrieve": "Retrieve an inventory from a project", "projects_notification_templates_error_create": "Create a notification template for project error events", @@ -282,7 +282,7 @@ "projects_notification_templates_success_list": "List notification templates for project success events", "projects_object_roles_list": "List roles of a project", "projects_partial_update": "Update a project", - "projects_playbooks_retrieve": "Retrieve single playbook for a project", + "projects_playbooks_retrieve": "Returns the list of playbook files available in a specific project by ID.", "projects_project_updates_list": "List project updates of a project", "projects_retrieve": "Retrieve a project", "projects_schedules_create": "Create a schedule of a project", @@ -318,7 +318,7 @@ "roles_retrieve": "Retrieve a role", "roles_teams_list": "List teams with a role", "roles_users_list": "List users with a role", - "schedules_create": "Create a schedule", + "schedules_create": "Create a schedule for recurring automated execution of a job template, workflow job template, project sync, inventory sync or management job.", "schedules_credentials_create": "Create a credential of a schedule", "schedules_credentials_list": "List credentials of a schedule", "schedules_destroy": "Delete a schedule", @@ -351,7 +351,7 @@ "service_index_role_user_assignments_unassign_create": "Create new service index role user assignments unassign", "settings_destroy": "Delete existing setting", "settings_logging_test_create": "Create new settings logging test", - "settings_retrieve": "Retrieve single setting", + "settings_retrieve": "Returns Controller settings for a specific category by slug.", "settings_update": "Update existing setting", "system_job_templates_jobs_list": "List system jobs of a system job template", "system_job_templates_notification_templates_error_create": "Create a notification templates triggered on system job error", @@ -384,7 +384,7 @@ "teams_update": "Update a team", "teams_users_create": "Create a user of a team", "teams_users_list": "List users of a team", - "unified_job_templates_list": "List unified job templates", + "unified_job_templates_list": "Returns a paginated list of all unified job templates. Combines job templates, workflow templates, and project updates in a single view.", "unified_jobs_list": "List unified jobs", "users_access_list_list": "List users who can access the user", "users_activity_stream_list": "List activity stream for a user", diff --git a/awx/api/views/__init__.py b/awx/api/views/__init__.py index 02df14859c..1344a0bdd7 100644 --- a/awx/api/views/__init__.py +++ b/awx/api/views/__init__.py @@ -890,7 +890,7 @@ class ExecutionEnvironmentList(ListCreateAPIView): 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"}) + @extend_schema_if_available(extensions={"x-ai-description": "Create a new execution environment container image reference."}) def post(self, request, *args, **kwargs): return super().post(request, *args, **kwargs) @@ -963,7 +963,9 @@ class ProjectList(ListCreateAPIView): serializer_class = serializers.ProjectSerializer resource_purpose = 'projects' - @extend_schema_if_available(extensions={"x-ai-description": "A list of projects."}) + @extend_schema_if_available( + extensions={"x-ai-description": "Returns a paginated list of all projects. Projects represent playbook collections sourced from version control."} + ) def get(self, request, *args, **kwargs): return super().get(request, *args, **kwargs) @@ -1385,7 +1387,7 @@ class CredentialTypeList(ListCreateAPIView): serializer_class = serializers.CredentialTypeSerializer resource_purpose = 'credential types' - @extend_schema_if_available(extensions={"x-ai-description": "A list of credential types"}) + @extend_schema_if_available(extensions={"x-ai-description": "Returns a paginated list of all credential types (machine, vault, cloud, etc.)."}) def get(self, request, *args, **kwargs): return super().get(request, *args, **kwargs) @@ -2071,11 +2073,11 @@ class GroupList(ListCreateAPIView): serializer_class = serializers.GroupSerializer resource_purpose = 'groups' - @extend_schema_if_available(extensions={"x-ai-description": "A list of groups."}) + @extend_schema_if_available(extensions={"x-ai-description": "Returns a paginated list of all host 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."}) + @extend_schema_if_available(extensions={"x-ai-description": "Create a new host group within an inventory."}) def post(self, request, *args, **kwargs): return super().post(request, *args, **kwargs) @@ -2281,7 +2283,7 @@ 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."}) + @extend_schema_if_available(extensions={"x-ai-description": "Returns the extra variables (YAML/JSON) configured for a specific host by ID."}) def get(self, request, *args, **kwargs): return super().get(request, *args, **kwargs) @@ -2575,7 +2577,9 @@ class InventorySourceUpdateView(RetrieveAPIView): serializer_class = serializers.InventorySourceUpdateSerializer resource_purpose = 'update an inventory source' - @extend_schema_if_available(extensions={"x-ai-description": "Sync the inventory source"}) + @extend_schema_if_available( + extensions={"x-ai-description": "Trigger a sync of an inventory source by ID. Pulls latest host data from the external source."} + ) def post(self, request, *args, **kwargs): obj = self.get_object() serializer = self.get_serializer(instance=obj, data=request.data) @@ -2635,7 +2639,11 @@ class JobTemplateList(ListCreateAPIView): always_allow_superuser = False resource_purpose = 'job templates' - @extend_schema_if_available(extensions={"x-ai-description": "A list of job templates."}) + @extend_schema_if_available( + extensions={ + "x-ai-description": "Returns a paginated list of all job templates. A job template defines the playbook, inventory, credentials, and settings for launching a job." + } + ) def get(self, request, *args, **kwargs): return super().get(request, *args, **kwargs) @@ -2724,7 +2732,9 @@ class JobTemplateLaunch(RetrieveAPIView): return modern_data - @extend_schema_if_available(extensions={"x-ai-description": "Launch the job template"}) + @extend_schema_if_available( + extensions={"x-ai-description": "Launch a job from a job template by ID. Starts execution of the playbook defined in the template."} + ) def post(self, request, *args, **kwargs): obj = self.get_object() @@ -2807,7 +2817,11 @@ class JobTemplateSurveySpec(GenericAPIView): obj = self.get_object() return Response(obj.display_survey_spec()) - @extend_schema_if_available(extensions={"x-ai-description": "Update job template survey specification"}) + @extend_schema_if_available( + extensions={ + "x-ai-description": "Create or update the survey specification for a job template. Surveys prompt users for input variables at launch time." + } + ) def post(self, request, *args, **kwargs): obj = self.get_object() @@ -3423,7 +3437,11 @@ 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."}) + @extend_schema_if_available( + extensions={ + "x-ai-description": "Returns a paginated list of all workflow job templates. Workflow templates chain multiple node types—job templates, other workflows, project syncs, inventory syncs, management jobs, and approval gates—into a single automated workflow." + } + ) def get(self, request, *args, **kwargs): return super().get(request, *args, **kwargs) @@ -3590,7 +3608,9 @@ 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 previously completed or failed workflow job using the same parameters as the original run."} + ) def post(self, request, *args, **kwargs): obj = self.get_object() if obj.is_sliced_job: @@ -3954,7 +3974,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 previously completed or failed job using the same parameters as the original run."}) def post(self, request, *args, **kwargs): obj = self.get_object() context = self.get_serializer_context() @@ -4724,7 +4744,7 @@ class NotificationTemplateList(ListCreateAPIView): 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."}) + @extend_schema_if_available(extensions={"x-ai-description": "Create a new notification template (email, Slack, webhook, etc.)."}) def post(self, request, *args, **kwargs): return super().post(request, *args, **kwargs) diff --git a/awx/api/views/analytics.py b/awx/api/views/analytics.py index 890307dc7c..3e0dca9170 100644 --- a/awx/api/views/analytics.py +++ b/awx/api/views/analytics.py @@ -51,7 +51,7 @@ class AnalyticsRootView(APIView): name = _('Automation Analytics') resource_purpose = 'automation analytics endpoints' - @extend_schema_if_available(extensions={"x-ai-description": "A list of additional API endpoints related to analytics"}) + @extend_schema_if_available(extensions={"x-ai-description": "Returns available analytics API endpoints and their descriptions."}) def get(self, request, format=None): data = OrderedDict() data['authorized'] = reverse('api:analytics_authorized', request=request) diff --git a/awx/api/views/root.py b/awx/api/views/root.py index 248f342d11..4f01bf2d23 100644 --- a/awx/api/views/root.py +++ b/awx/api/views/root.py @@ -323,7 +323,7 @@ class ApiV2ConfigView(APIView): self.permission_denied(request) # Raises PermissionDenied exception. @extend_schema_if_available( - extensions={'x-ai-description': 'Return various configuration settings'}, + extensions={'x-ai-description': 'Returns platform-level configuration and license info.'}, ) def get(self, request, format=None): '''Return various sitewide configuration settings''' diff --git a/awx/conf/views.py b/awx/conf/views.py index b38c9c5e14..9bff2af186 100644 --- a/awx/conf/views.py +++ b/awx/conf/views.py @@ -42,7 +42,7 @@ 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."}) + @extend_schema_if_available(extensions={"x-ai-description": "Returns a paginated list of Controller setting categories."}) def get(self, request, *args, **kwargs): return super().get(request, *args, **kwargs)