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);
 
@@ -169,44 +181,50 @@ private function addPostArgumentUsageToExample(mixed $requestBody, mixed $propKe
     {
         $requestBodyContent = $this->getRequestBodyContent($requestBody, $acquiaCloudSpec);
 
+        // Example may live directly on the content-type object, or nested inside schema (e.g. $ref-resolved requestBodies).
         if (array_key_exists('example', $requestBodyContent)) {
             $example = $requestBodyContent['example'];
-            $prefix = $type === 'argument' ? '' : "--$propKey=";
-            if (array_key_exists($propKey, $example)) {
-                if (!array_key_exists('type', $paramDefinition)) {
-                    return $usage;
-                }
-                switch ($paramDefinition['type']) {
-                    case 'object':
-                        $usage .= $prefix . '"' . json_encode($example[$propKey], JSON_THROW_ON_ERROR) . '"" ';
-                        break;
-
-                    case 'array':
-                        $isMultidimensional = count($example[$propKey]) !== count($example[$propKey], COUNT_RECURSIVE);
-                        if (!$isMultidimensional) {
-                            foreach ($example[$propKey] as $value) {
-                                $usage .= $prefix . "\"$value\" ";
-                            }
-                        } else {
-                            // @todo Pretty sure prevents the user from using the arguments.
-                            // Probably a bug. How can we allow users to specify a multidimensional array as an
-                            // argument?
-                            $value = json_encode($example[$propKey], JSON_THROW_ON_ERROR);
+        } elseif (array_key_exists('schema', $requestBodyContent) && array_key_exists('example', $requestBodyContent['schema'])) {
+            $example = $requestBodyContent['schema']['example'];
+        } else {
+            return $usage;
+        }
+
+        $prefix = $type === 'argument' ? '' : "--$propKey=";
+        if (array_key_exists($propKey, $example)) {
+            if (!array_key_exists('type', $paramDefinition)) {
+                return $usage;
+            }
+            switch ($paramDefinition['type']) {
+                case 'object':
+                    $usage .= $prefix . '"' . json_encode($example[$propKey], JSON_THROW_ON_ERROR) . '" ';
+                    break;
+
+                case 'array':
+                    $isMultidimensional = count($example[$propKey]) !== count($example[$propKey], COUNT_RECURSIVE);
+                    if (!$isMultidimensional) {
+                        foreach ($example[$propKey] as $value) {
                             $usage .= $prefix . "\"$value\" ";
                         }
-                        break;
-
-                    case 'string':
-                    case 'boolean':
-                    case 'integer':
-                        if (is_array($example[$propKey])) {
-                            $value = reset($example[$propKey]);
-                        } else {
-                            $value = $example[$propKey];
-                        }
+                    } else {
+                        // @todo Pretty sure prevents the user from using the arguments.
+                        // Probably a bug. How can we allow users to specify a multidimensional array as an
+                        // argument?
+                        $value = json_encode($example[$propKey], JSON_THROW_ON_ERROR);
                         $usage .= $prefix . "\"$value\" ";
-                        break;
-                }
+                    }
+                    break;
+
+                case 'string':
+                case 'boolean':
+                case 'integer':
+                    if (is_array($example[$propKey])) {
+                        $value = reset($example[$propKey]);
+                    } else {
+                        $value = $example[$propKey];
+                    }
+                    $usage .= $prefix . "\"$value\" ";
+                    break;
             }
         }
         return $usage;
@@ -482,10 +500,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] ?? null;
+
+        // 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 (is_array($spec) && array_key_exists('$ref', $spec)) {
+            $parts = explode('/', $spec['$ref']);
+            $paramKey = end($parts);
+            $spec = $this->getParameterSchemaFromSpec($paramKey, $acquiaCloudSpec);
+        }
+
+        return $spec;
     }
 
     /**