foreman_ansible_director 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a4d8ce033fdae658dc74ed39b1e726223fd1f3f709c0912500eee63a959d1cfb
-  data.tar.gz: ff49758a3a1ab2654d8af19e4841eda385c14d3338e8fc1d925cbd53863265b2
+  metadata.gz: 9bfa5c13b50ecdad46dceeb00e2691c16c586e8060094b5fe21eb1b19ae0eb60
+  data.tar.gz: 12749d98c77fe7008baf803bdfcc627b428f82f1192da8f904602611dbbac9f6
 SHA512:
-  metadata.gz: c65a3a229e2b3d482e3144dcfd0eb8a4c5de8e70acc1a089f09234686267ac0c597f98b9308e8b1d438be43c7e0b5301ee9e3d2ea86558656e2b52482e38897f
-  data.tar.gz: 165890d464e01ce17f4e673fe7ab88d4c391a28a34ce37f13274c1459d5fe37613c8ed8e4d3daf84ca14cc37a276a3f9400fb9647c09c0b6df11f625901bb9d3
+  metadata.gz: 8650021501539c07fc71f21cacaea22dae5abe0066b209354b9ae68b8bc2d802c7ea5440c55df65b3d53f5b218b67bcbdb7d88c9699cd6c2219bd46749c69e17
+  data.tar.gz: 5537935a1c0f62ca5a3465b7fc998bb713e8dd22a2fdfa193b5db14a6e1176367112268124f2bb879d139bd8740706e44d620347c60e40e251c6386975130efb

data/app/controllers/foreman_ansible_director/api/v2/ansible_content_controller.rb

@@ -7,19 +7,72 @@ module ForemanAnsibleDirector
         before_action :find_organization, only: %i[create_units]
         before_action :find_optional_organization, only: %i[index]
 
-        # TODO: APIDOC
+        resource_description { resource_id 'AD Ansible Content' }
 
+        # region ApiDoc: POST /api/v2/ansible_director/ansible_content
+        api :POST, '/v2/ansible_director/ansible_content', N_('Import Ansible content units')
+        param :organization_id, :number, desc: N_('Organization identifier.'), required: true
+        param :units, Array, desc: N_('Array of content units to import.'), required: true do
+          param :unit_name,
+            String,
+            desc: N_('Identifier of the content unit.'),
+            example: N_('manala.roles'),
+            required: true
+          param :unit_type,
+            %w[role collection],
+            desc: N_('Type of the content unit.'),
+            example: N_('collection'),
+            required: true
+          param :unit_source_type,
+            %w[galaxy git],
+            desc: N_('Source type of the content unit.'),
+            example: N_('galaxy'),
+            required: true
+          param :unit_source,
+            String,
+            desc: N_('Source URL or path for the content unit (e.g., Galaxy URL or Git repo).'),
+            example: N_('https://galaxy.ansible.com'),
+            required: true
+          param :unit_versions,
+            Array,
+            desc: N_('An array of versions to import (e.g., ["1.0.0", "2.0.0"]).'),
+            example: %w[1.0.0 2.0.0],
+            required: true
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "organization_id": 1,
+            "units": [
+              {
+                "unit_name": "manala.roles",
+                "unit_type": "collection",
+                "unit_source_type": "galaxy",
+                "unit_source": "https://galaxy.ansible.com",
+                "unit_versions": ["5.2.0"]
+              }
+            ]
+          }
+        EXAMPLE
+        # endregion
         def create_units
           resolved = ::ForemanAnsibleDirector::AnsibleContent::AnsibleContentHelpers.resolve_import_payload(
             params[:units]
           )
-          @bulk_create_task = ForemanTasks.sync_task(
+          @bulk_create_task = ::ForemanAnsibleDirector::ActionService.trigger(
             ::ForemanAnsibleDirector::Actions::AnsibleContentUnit::Bulk::Import,
-            resolved_content_units: resolved,
-            organization_id: @organization.id
+            task_args: {
+              resolved_content_units: resolved,
+              organization_id: @organization.id,
+            }
           )
         end
 
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_content
+        api :GET, '/v2/ansible_director/ansible_content', N_('List Ansible content units')
+        param :organization_id, :number, desc: N_('Organization identifier'), required: false
+        param_group :search_and_pagination, ::Api::V2::BaseController
+        # endregion
         def index
           scope = resource_scope_for_index
           @ansible_content_units = if @organization
@@ -29,18 +82,64 @@ module ForemanAnsibleDirector
                                    end
         end
 
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_content/:content_unit_id/versions/:content_unit_version_id
+        api :GET, '/v2/ansible_director/ansible_content/:content_unit_id/versions/:content_unit_version_id',
+          N_('Show details of a specific Ansible content unit version')
+        # endregion
         def version_detail
           @content_unit_version = ::ForemanAnsibleDirector::ContentUnitVersion.find_by(id: params[:version])
         end
 
         # TODO: This needs to check and invalidate built EEs
+        # region ApiDoc: DELETE /api/v2/ansible_director/ansible_content
+        api :DELETE, '/v2/ansible_director/ansible_content',
+          N_('Destroy previously imported Ansible content units.')
+        param :units, Array, desc: N_('Array of content units to destroy.'), required: true do
+          param :unit_id, :number, desc: N_('ID of the Ansible content unit to destroy.'), required: true
+          # TRANSLATORS: ApiDoc, do not translate!
+          param :unit_version_ids, Array,
+            desc: <<~DESC,
+              Array of version IDs to delete.
+              Optional: If not supplied, every version of the given content unit will be deleted.
+            DESC
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "units": [
+              {
+                "unit_id": 42,
+                "unit_version_ids": [101, 102]
+              },
+              {
+                "unit_id": 43,
+                "unit_version_ids": [105]
+              }
+            ]
+          }
+        EXAMPLE
+        # endregion
         def destroy_units
           resolved = ::ForemanAnsibleDirector::AnsibleContent::AnsibleContentHelpers.resolve_destroy_payload(
             destroy_params
           )
-          @bulk_destroy_task =
-            ForemanTasks.sync_task(::ForemanAnsibleDirector::Actions::AnsibleContentUnit::Bulk::Destroy,
-              resolved_content_units: resolved, organization_id: @organization.id)
+          @bulk_destroy_task = ::ForemanAnsibleDirector::ActionService.trigger(
+            ::ForemanAnsibleDirector::Actions::AnsibleContentUnit::Bulk::Destroy,
+            task_args: {
+              resolved_content_units: resolved,
+            }
+          )
+        end
+
+        # region ApiDoc: POST /api/v2/ansible_director/ansible_content/consistency_check
+        api :POST, '/v2/ansible_director/ansible_content/consistency_check',
+          N_('Run a consistency check to clean up the database after a failed content import.')
+        # endregion
+        def consistency_check
+          @consistency_check = ::ForemanAnsibleDirector::ActionService.trigger(
+            ::ForemanAnsibleDirector::Actions::ConsistencyCheck::Perform
+          )
         end
 
         def model_of_controller

data/app/controllers/foreman_ansible_director/api/v2/ansible_director_api_controller.rb

@@ -7,6 +7,19 @@ module ForemanAnsibleDirector
         include ::Api::Version2
         include ::Foreman::Controller::AutoCompleteSearch
 
+        include ::ForemanAnsibleDirector::RequestCtx::RequestContextHelper
+
+        around_action :attach_request_ctx
+
+        def attach_request_ctx
+          ::ForemanAnsibleDirector::RequestCtx::RequestContext.with_context(
+            ::ForemanAnsibleDirector::RequestCtx::RequestContext.new(request.request_id)
+          ) do
+            @ctx = ctx
+            yield
+          end
+        end
+
         def find_organization
           @organization = Organization.current || find_optional_organization
           if @organization.nil?

data/app/controllers/foreman_ansible_director/api/v2/ansible_variable_overrides_controller.rb

@@ -7,6 +7,30 @@ module ForemanAnsibleDirector
         before_action :find_variable, only: %i[create]
         before_action :find_override, only: %i[update destroy]
 
+        resource_description { resource_id 'AD Ansible Variable Overrides' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides
+        api :GET, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides',
+          N_('List overrides for a target')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          List override values associated with a given target (host or hostgroup).
+          Overrides are matched at runtime based on the predefined hierarchy: Default -> Hostgroup -> Host.
+        DESC
+        param :target,
+          %w[HOST HOSTGROUP],
+          desc: N_('Type of the target entity.'),
+          required: true
+        param :target_id,
+          :number,
+          desc: N_('ID of the target entity.'),
+          required: true
+        param :include_overridable,
+          [true, false],
+          desc: N_('Whether to include overridable variables in the response.'),
+          example: false,
+          required: false
+        # endregion
         def index_for_target
           target = ::ForemanAnsibleDirector::AssignmentService.find_target(
             target_type: params[:target],
@@ -17,6 +41,46 @@ module ForemanAnsibleDirector
             include_overridable: include_overridable
         end
 
+        # region ApiDoc: POST /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides
+        api :POST, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides',
+          N_('Create an override for an Ansible variable')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Create a new override rule for the specified Ansible variable.
+          Overrides allow customizing the variable value for specific hosts, hostgroups, or other matchers.
+        DESC
+        param :ansible_variable_id,
+          :number,
+          desc: N_('ID of the Ansible variable to override.'),
+          required: true
+        param :override, Hash, desc: N_('Override definition'), required: true do
+          param :value,
+            String,
+            desc: N_('Override value (must be valid JSON when the variable type is `json`, `array`, or `hash`).'),
+            example: '192.168.1.1',
+            required: true
+          param :matcher,
+            %w[fqdn hostgroup],
+            desc: N_('Matcher type.'),
+            example: 'fqdn',
+            required: true
+          param :matcher_value,
+            String,
+            desc: N_('Value for the matcher (e.g., "myhost.example.com").'),
+            example: 'myhost.example.com',
+            required: true
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "override": {
+              "value": "prod-ntp.internal",
+              "matcher": "fqdn",
+              "matcher_value": "prod-web-01.example.com"
+            }
+          }
+        EXAMPLE
+        # endregion
         def create
           override = override_params
           ::ForemanAnsibleDirector::VariableService.create_override(
@@ -27,6 +91,48 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: PUT /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id
+        api :PUT, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id', N_('Update an override')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Update an existing override rule.
+        DESC
+        param :ansible_variable_id,
+          :number,
+          desc: N_('ID of the Ansible variable.'),
+          required: true
+        param :id,
+          :number,
+          desc: N_('ID of the override to update.'),
+          required: true
+        param :override, Hash, desc: N_('Override update'), required: true do
+          param :value,
+            String,
+            desc: N_('New override value.'),
+            example: 'backup-ntp.internal',
+            required: false
+          param :matcher,
+            String,
+            desc: N_('New matcher type (e.g., "hostgroup").'),
+            example: 'hostgroup',
+            required: false
+          param :matcher_value,
+            String,
+            desc: N_('New matcher value (e.g., "my_hostgroup").'),
+            example: 'my_hostgroup',
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "override": {
+              "value": "staging-ntp.internal",
+              "matcher": "hostgroup",
+              "matcher_value": "Staging"
+            }
+          }
+        EXAMPLE
+        # endregion
         def update
           override = override_params
           ::ForemanAnsibleDirector::VariableService.edit_override(
@@ -37,6 +143,22 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: DELETE /api/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id
+        api :DELETE, '/v2/ansible_director/ansible_variables/:ansible_variable_id/overrides/:id',
+          N_('Delete an override')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Delete an override rule.
+        DESC
+        param :ansible_variable_id,
+          :number,
+          desc: N_('ID of the Ansible variable.'),
+          required: true
+        param :id,
+          :number,
+          desc: N_('ID of the override to delete.'),
+          required: true
+        # endregion
         def destroy
           ::ForemanAnsibleDirector::VariableService.destroy_override(@override)
         end
@@ -71,6 +193,10 @@ module ForemanAnsibleDirector
             }
           )
         end
+
+        def controller_permission
+          'ansible_director_variable_overrides'
+        end
       end
     end
   end

data/app/controllers/foreman_ansible_director/api/v2/ansible_variables_controller.rb

@@ -6,9 +6,58 @@ module ForemanAnsibleDirector
       class AnsibleVariablesController < AnsibleDirectorApiController
         before_action :find_resource, only: %i[show update]
 
+        resource_description { resource_id 'AD Ansible Variables' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/ansible_variables/:id
+        api :GET, '/v2/ansible_director/ansible_variables/:id', N_('Show details of an Ansible variable')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Retrieve details of a specific Ansible variable.
+        DESC
+        # endregion
         def show
         end
 
+        # region ApiDoc: PUT /api/v2/ansible_director/ansible_variables/:id
+        api :PUT, '/v2/ansible_director/ansible_variables/:id', N_('Update an Ansible variable')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Update basic attributes (key, type, default value, and overridability) of an Ansible variable.
+        DESC
+        param :ansible_variable, Hash, desc: N_('Ansible variable updates'), required: true do
+          param :key,
+            String,
+            desc: N_('Name of the variable.'),
+            example: 'ansible_user',
+            required: true
+          param :type,
+            %w[string integer boolean float json array hash],
+            desc: N_('Type of the variable value.'),
+            example: 'string',
+            required: true
+          param :default_value,
+            String,
+            desc: N_('Default value (must be valid JSON when type is `json`, `array`, or `hash`).'),
+            example: 'root',
+            required: true
+          param :overridable,
+            [true, false],
+            desc: N_('Whether this variable can be overridden on hosts or hostgroups.'),
+            example: true,
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "ansible_variable": {
+              "key": "ansible_user",
+              "type": "string",
+              "default_value": "root",
+              "overridable": true
+            }
+          }
+        EXAMPLE
+        # endregion
         def update
           variable = variable_params
           ::ForemanAnsibleDirector::VariableService.edit_variable(
@@ -29,6 +78,10 @@ module ForemanAnsibleDirector
         def resource_class
           ::ForemanAnsibleDirector::AnsibleVariable
         end
+
+        def controller_permission
+          'ansible_director_variables'
+        end
       end
     end
   end

data/app/controllers/foreman_ansible_director/api/v2/assignments_controller.rb

@@ -6,41 +6,114 @@ module ForemanAnsibleDirector
       class AssignmentsController < AnsibleDirectorApiController
         before_action :find_resource, only: %i[destroy]
 
+        resource_description { resource_id 'AD Ansible Content Assignments' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/assignments/:target/:target_id
+        api :GET, '/v2/ansible_director/assignments/:target/:target_id',
+          N_('List Ansible content assignments for a target')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Retrieve all Ansible content units for a given target (host or hostgroup).
+          This includes content inherited through the assignment hierarchy and direct assignments.
+          If resolve is true, the server will try to map the assignment to an actual content unit available to target.
+        DESC
+        param :target,
+          %w[host hostgroup],
+          desc: N_('Type of the target entity.'),
+          required: true
+        param :target_id,
+          :number,
+          desc: N_('ID of the target entity.'),
+          required: true
+        param :resolve,
+          :boolean,
+          desc: N_('Resolve content units for assignments.'),
+          required: false
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          GET /api/v2/ansible_director/assignments/host/1
+        EXAMPLE
+        # endregion
         def assignments
           target = ::ForemanAnsibleDirector::AssignmentService.find_target(
             target_type: params[:target],
             target_id: params[:target_id]
           )
           # TODO: Null check target
-          @assignments = target.resolved_ansible_content
+          @assignments, @resolved_assignments, @hierarchy = ::ForemanAnsibleDirector::AssignmentService.assignments_for(
+            target: target,
+            resolve: ::Foreman::Cast.to_bool(params[:resolve])
+          )
         end
 
+        # region ApiDoc: POST /api/v2/ansible_director/assignments/:target/:target_id
+        api :POST, '/v2/ansible_director/assignments/:target/:target_id', N_('Assign Ansible content.')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Create Ansible content assignments for a target.
+          An assignment represents an Ansible role or Ansible collection role.
+          The version of this role is determined dynamically.
+        DESC
+        param :assignments, Array, desc: N_('Array of assignment objects.'), required: true do
+          param :assignable_type,
+            %w[ForemanAnsibleDirector::AnsibleCollectionRole ForemanAnsibleDirector::AnsibleRole],
+            desc: N_('Type of the Ansible content unit.'),
+            required: true
+          param :assignable_namespace,
+            String,
+            desc: N_('Namespace of the Ansible content unit.'),
+            required: true
+          param :assignable_name,
+            String,
+            desc: N_('Name of the Ansible content unit.'),
+            required: true
+          param :assignable_role_name,
+            String,
+            desc: <<~DESC,
+              Only required if assignable_type = "ForemanAnsibleDirector::AnsibleCollectionRole".
+              An identifier of a role in the supplied collection.
+              $assignable_namespace.$assignable_name.$assignable_role_name must form a fully qualified role name.
+            DESC
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "assignments": [
+              {
+                "assignable_type": "ForemanAnsibleDirector::AnsibleCollectionRole",
+                "assignable_namespace": "manala",
+                "assignable_name": "roles",
+                "assignable_role_name": "motd"
+              }
+            ]
+          }
+        EXAMPLE
+        # endregion
         def assign
-          assignment = assignment_params
-
-          source = ::ForemanAnsibleDirector::AssignmentService.find_target(
-            target_type: assignment[:source][:type],
-            target_id: assignment[:source][:id]
-          )
-
           target = ::ForemanAnsibleDirector::AssignmentService.find_target(
-            target_type: assignment[:target][:type],
-            target_id: assignment[:target][:id]
-          )
-
-          ::ForemanAnsibleDirector::AssignmentService.create_assignment(
-            consumable: source,
-            assignable: target
+            target_type: params[:target],
+            target_id: params[:target_id]
           )
-        end
 
-        def assign_bulk
           assignments = bulk_assignment_params
           ::ForemanAnsibleDirector::AssignmentService.create_bulk_assignments(
+            target: target,
             assignments: assignments
           )
         end
 
+        # region ApiDoc: DELETE /api/v2/ansible_director/assignments/:id
+        api :DELETE, '/v2/ansible_director/assignments/:id', N_('Delete an Ansible content assignment')
+        # TRANSLATORS: ApiDoc, do not translate!
+        description <<~DESC
+          Note: This deletes the assignment record but not the underlying Ansible content.
+        DESC
+        param :id,
+          :number,
+          desc: N_('ID of the assignment to delete.'),
+          required: true
+        # endregion
         def destroy
           ::ForemanAnsibleDirector::AssignmentService.destroy_assignment(@assignment)
         end
@@ -62,10 +135,7 @@ module ForemanAnsibleDirector
           return [] if params[:assignments].empty?
 
           params.require(:assignments).map do |assignment|
-            assignment.permit(
-              source: %i[type id],
-              target: %i[type id]
-            )
+            assignment.permit(:assignable_type, :assignable_namespace, :assignable_name, :assignable_role_name)
           end
         end
       end

data/app/controllers/foreman_ansible_director/api/v2/execution_environments_controller.rb

@@ -6,13 +6,64 @@ module ForemanAnsibleDirector
       class ExecutionEnvironmentsController < AnsibleDirectorApiController
         include ::Api::Version2
 
-        before_action :find_resource, only: %i[update destroy]
+        before_action :find_resource, only: %i[show update destroy]
         before_action :find_organization, only: %i[create]
 
+        resource_description { resource_id 'AD Ansible Execution Environments' }
+
+        # region ApiDoc: GET /api/v2/ansible_director/execution_environments
+        api :GET, '/v2/ansible_director/execution_environments', N_('List all execution environments')
+        param :organization_id, :number, desc: N_('Organization identifier.'), required: false
+        param_group :search_and_pagination, ::Api::V2::BaseController
+        # endregion
         def index
           @execution_environments = resource_scope_for_index
         end
 
+        # region ApiDoc: GET /api/v2/ansible_director/execution_environments/:id
+        api :GET, '/v2/ansible_director/execution_environments/:id', N_('Show details of an execution environment')
+        param :id, :number, desc: N_('Execution Environment identifier.'), required: true
+        # endregion
+        def show
+        end
+
+        # region ApiDoc: POST /api/v2/ansible_director/execution_environments
+        api :POST, '/v2/ansible_director/execution_environments', N_('Create an Execution Environment')
+        param :organization_id, :number, desc: N_('Organization identifier'), required: true
+        param :execution_environment, Hash, desc: N_('Execution Environment definition'), required: true do
+          param :name,
+            String,
+            desc: N_('Execution Environment name.'),
+            example: 'MyExecutionEnvironment',
+            required: true
+          param :base_image_url,
+            String,
+            desc: N_('Execution Environment base image URL. The image must be pullable by an unauthenticated user.'),
+            example: 'registry.fedoraproject.org/fedora:43',
+            required: true
+          # TRANSLATORS: ApiDoc, do not translate!
+          param :ansible_version,
+            String,
+            desc: <<~DESC,
+              Version of "ansible-core" to be used in this execution environment.
+              The version must match one of the available releases.
+              See: https://pypi.org/project/ansible-core/#history
+            DESC
+            example: ::ForemanAnsibleDirector::Constants::DEFAULT_ANSIBLE_VERSION,
+            required: true
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "organization_id": 1,
+            "execution_environment": {
+              "name": "EE-2.20.0",
+              "base_image_url": "quay.io/fedora/fedora:42",
+              "ansible_version": "2.20.0"
+            }
+          }
+        EXAMPLE
+        # endregion
         def create
           permitted_params = execution_environment_params
           # content = permitted_params.delete(:content)
@@ -25,6 +76,41 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: PATCH /api/v2/ansible_director/execution_environments/:id
+        api :PATCH, '/v2/ansible_director/execution_environments/:id', N_('Update an Execution Environment')
+        param :execution_environment, Hash, desc: N_('Execution Environment definition'), required: true do
+          param :name,
+            String,
+            desc: N_('Execution Environment name.'),
+            example: 'MyExecutionEnvironment',
+            required: false
+          param :base_image_url,
+            String,
+            desc: N_('Execution Environment base image URL. The image must be pullable by an unauthenticated user.'),
+            example: 'registry.fedoraproject.org/fedora:43',
+            required: false
+          # TRANSLATORS: ApiDoc, do not translate!
+          param :ansible_version,
+            String,
+            desc: <<~DESC,
+              Version of "ansible-core" to be used in this execution environment.
+              The version must match one of the available releases.
+              See: https://pypi.org/project/ansible-core/#history
+            DESC
+            example: ::ForemanAnsibleDirector::Constants::DEFAULT_ANSIBLE_VERSION,
+            required: false
+        end
+        # TRANSLATORS: ApiDoc, do not translate!
+        example <<~EXAMPLE
+          {
+            "execution_environment": {
+              "name": "EE-2.20.0",
+              "base_image_url": "quay.io/fedora/fedora:42",
+              "ansible_version": "2.20.0"
+            }
+          }
+        EXAMPLE
+        # endregion
         def update
           permitted_params = execution_environment_params
           # content = permitted_params.delete(:content)
@@ -37,6 +123,9 @@ module ForemanAnsibleDirector
           )
         end
 
+        # region ApiDoc: DELETE /api/v2/ansible_director/execution_environments/:id
+        api :DELETE, '/v2/ansible_director/execution_environments/:id', N_('Delete an Execution Environment')
+        # endregion
         def destroy
           @execution_environment.destroy
           ::ForemanAnsibleDirector::ExecutionEnvironmentService.destroy_execution_environment @execution_environment