CLI-1745: fix: resolve pointers in requestBody and property schemas for API commands.

Author: vishalkhode1

src/Command/Api/ApiBaseCommand.php

@@ -245,7 +245,7 @@ private function castParamType(array $paramSpec, array|string|bool|int $value):
             if (in_array('integer', $types, true) && ctype_digit($value)) {
                 return $this->doCastParamType('integer', $value);
             }
-        } elseif ($paramSpec['type'] === 'array') {
+        } elseif ($this->getParamType($paramSpec) === 'array') {
             if (is_array($value) && count($value) === 1) {
                 return $this->castParamToArray($paramSpec, $value[0]);
             }

src/Command/Api/ApiCommandHelper.php

@@ -86,14 +86,20 @@ private function addApiCommandParameters(array $schema, array $acquiaCloudSpec,
 
         // Parameters to be used in the request body.
         if (array_key_exists('requestBody', $schema)) {
+            // Resolve $ref in requestBody if present.
+            if (array_key_exists('$ref', $schema['requestBody'])) {
+                $parts = explode('/', $schema['requestBody']['$ref']);
+                $paramKey = end($parts);
+                $schema['requestBody'] = $acquiaCloudSpec['components']['requestBodies'][$paramKey];
+            }
             [
                 $bodyInputDefinition,
                 $requestBodyParamUsageSuffix,
             ] = $this->addApiCommandParametersForRequestBody($schema, $acquiaCloudSpec);
             $requestBodySchema = $this->getRequestBodyFromParameterSchema($schema, $acquiaCloudSpec);
             /** @var \Symfony\Component\Console\Input\InputOption|InputArgument $parameterDefinition */
             foreach ($bodyInputDefinition as $parameterDefinition) {
-                $parameterSpecification = $this->getPropertySpecFromRequestBodyParam($requestBodySchema, $parameterDefinition);
+                $parameterSpecification = $this->getPropertySpecFromRequestBodyParam($requestBodySchema, $parameterDefinition, $acquiaCloudSpec);
                 $command->addPostParameter($parameterDefinition->getName(), $parameterSpecification);
             }
             $usage .= $requestBodyParamUsageSuffix;
@@ -125,6 +131,12 @@ private function addApiCommandParametersForRequestBody(array $schema, array $acq
             $requestBodySchema['properties'] = [];
         }
         foreach ($requestBodySchema['properties'] as $propKey => $paramDefinition) {
+            // Resolve $ref inside individual property definitions.
+            if (array_key_exists('$ref', $paramDefinition)) {
+                $parts = explode('/', $paramDefinition['$ref']);
+                $paramKey = end($parts);
+                $paramDefinition = $this->getParameterSchemaFromSpec($paramKey, $acquiaCloudSpec);
+            }
             $isRequired = array_key_exists('required', $requestBodySchema) && in_array($propKey, $requestBodySchema['required'], true);
             $propKey = self::renameParameter($propKey);
 
@@ -168,9 +180,17 @@ private function addApiCommandParametersForRequestBody(array $schema, array $acq
     private function addPostArgumentUsageToExample(mixed $requestBody, mixed $propKey, mixed $paramDefinition, string $type, string $usage, array $acquiaCloudSpec): string
     {
         $requestBodyContent = $this->getRequestBodyContent($requestBody, $acquiaCloudSpec);
-
+        // Example may live directly on the content-type object (inline requestBody),
+        // or nested inside schema (e.g. $ref-resolved requestBodies).
         if (array_key_exists('example', $requestBodyContent)) {
             $example = $requestBodyContent['example'];
+        } elseif (array_key_exists('schema', $requestBodyContent) && array_key_exists('example', $requestBodyContent['schema'])) {
+            $example = $requestBodyContent['schema']['example'];
+        } else {
+            return $usage;
+        }
+
+        if ($example) {
             $prefix = $type === 'argument' ? '' : "--$propKey=";
             if (array_key_exists($propKey, $example)) {
                 if (!array_key_exists('type', $paramDefinition)) {
@@ -482,10 +502,20 @@ private function getRequestBodyFromParameterSchema(array $schema, array $acquiaC
         return $requestBodySchema;
     }
 
-    private function getPropertySpecFromRequestBodyParam(array $requestBodySchema, mixed $parameterDefinition): mixed
+    private function getPropertySpecFromRequestBodyParam(array $requestBodySchema, mixed $parameterDefinition, array $acquiaCloudSpec = []): mixed
     {
         $name = self::restoreRenamedParameter($parameterDefinition->getName());
-        return $requestBodySchema['properties'][$name] ?? null;
+        $spec = $requestBodySchema['properties'][$name] ?? [];
+
+        // Resolve $ref in the property spec so downstream code (e.g. castParamType) always
+        // receives a fully resolved spec with a 'type' key rather than a bare $ref object.
+        if (array_key_exists('$ref', $spec)) {
+            $parts = explode('/', $spec['$ref']);
+            $paramKey = end($parts);
+            $spec = $this->getParameterSchemaFromSpec($paramKey, $acquiaCloudSpec);
+        }
+
+        return $spec;
     }
 
     /**

tests/phpunit/src/Commands/Api/ApiCommandTest.php

@@ -550,6 +550,11 @@ public static function providerTestApiCommandDefinitionRequestBody(): array
                 'post',
                 '12-d314739e-296f-11e9-b210-d663bd873d93 --source="14-0c7e79ab-1c4a-424e-8446-76ae8be7e851"',
             ],
+            [
+                'api:private-networks:create',
+                'post',
+                'api:private-networks:create "123e4567-e89b-12d3-a456-426614174000" "us-east-1" "customer-private-network" --description="Private network for customer" --label="anyLabel" --isolation="{"dedicated_compute":false,"dedicated_network":false}"" --ingress="{"drupal_ssh":{"ingress_acls":["test-acls"]}}"" "{"cidr":"114.7.55.1\/16","private_egress_access":{"drupal":true},"vpns":[{"name":"vpn1","gateway_ip":"10.10.10.10","routes":["127.0.0.1\/32","127.0.0.2\/32"],"tunnel1":{"shared_key":"sharedKey1","internal_cidr":"192.1.1.0\/24","ike_versions":"1","startup_action":"start","dpd_timeout_action":"stop"},"tunnel2":{"shared_key":"sharedKey2","internal_cidr":"192.1.1.0\/14","ike_versions":"1","startup_action":"start","dpd_timeout_action":"stop"}}],"vpc_peers":[{"name":"vpcPeer1","aws_account":"123456789012","vpc_id":"vpc-1234567890abcdef0","vpc_cidr":"120.24.16.1\/24"}]}""',
+            ],
         ];
     }
 
@@ -563,7 +568,15 @@ public function testApiCommandDefinitionRequestBody(string $commandName, string
     {
         $this->command = $this->getApiCommandByName($commandName);
         $resource = self::getResourceFromSpec($this->command->getPath(), $method);
-        foreach ($resource['requestBody']['content']['application/hal+json']['example'] as $propKey => $value) {
+        if (array_key_exists('$ref', $resource['requestBody'])) {
+            $cloudApiSpec = self::getCloudApiSpec();
+            $parts = explode('/', $resource['requestBody']['$ref']);
+            $paramKey = end($parts);
+            $resource['requestBody'] = $cloudApiSpec['components']['requestBodies'][$paramKey];
+        }
+        $example = $resource['requestBody']['content']['application/hal+json']['example'] ?? $resource['requestBody']['content']['application/json']['schema']['example'] ?? null;
+        self::assertNotEmpty($example);
+        foreach ($example as $propKey => $value) {
             $this->assertTrue(
                 $this->command->getDefinition()
                     ->hasArgument($propKey) || $this->command->getDefinition()