CLI-1745: Resolve $ref in requestBody and property schema for api:private-networks:create command.

[vishalkhode1]

Motivation
Fixes Undefined array key "type" warning that appears when running command acli api:private-networks:create.

Proposed changes

• Resolve $ref in requestBody object before processing parameters. For ex:

"requestBody": {
  "$ref": "#/components/requestBodies/Private_Network_Service_API_PrivateNetworkCreateRequest"
},

• Resolve $ref in individual property definitions from requestBody schema. For ex:

"isolation": {
  "$ref": "#/components/schemas/Private_Network_Service_API_Isolation"
},
"ingress": {
  "$ref": "#/components/schemas/Private_Network_Service_API_Ingress"
},
"connections": {
  "$ref": "#/components/schemas/Private_Network_Service_API_Connections"
}

• Add fallback to read example from schema.example for $ref resolved requestBodies.
• Use getParamType() helper in castParamType() instead of direct $paramSpec['type'] access to fix "Undefined array key type" warning.

Alternatives considered
N/A.

Testing steps

1. Run command ./bin/acli api:private-networks:create --help and you should proper example as added in acquia-spec.json.
2. Run below command and you shouldn't see any warning

./bin/acli 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"}]}"

1. Follow the contribution guide to set up your development environment or download a pre-built acli.phar for this PR.
2. If running from source, clear the kernel cache to pick up new and changed commands: ./bin/acli ckc
3. Check for regressions: (add specific steps for this pr)
4. Check new functionality: (add specific steps for this pr)

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.34%. Comparing base (064b748) to head (2e51bf3).

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #1973   +/-   ##
=========================================
  Coverage     92.33%   92.34%           
- Complexity     1932     1940    +8     
=========================================
  Files           122      122           
  Lines          7035     7051   +16     
=========================================
+ Hits           6496     6511   +15     
- Misses          539      540    +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Try the dev build for this PR: https://acquia-cli.s3.amazonaws.com/build/pr/1973/acli.phar

curl -OL https://acquia-cli.s3.amazonaws.com/build/pr/1973/acli.phar
chmod +x acli.phar

[Copilot]

Pull request overview

Fixes warnings and improves parameter/example handling for generated API CLI commands when the OpenAPI spec uses $ref in requestBody and in request-body property schemas (notably for api:private-networks:create).

Changes:

• Resolve $ref at the requestBody level and for $ref’d properties within the request-body schema before building CLI parameters.
• Add fallback support for requestBody examples located at content.<type>.schema.example (common with $ref-based requestBodies).
• Use getParamType() in castParamType() to avoid "Undefined array key type" warnings for array types.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
src/Command/Api/ApiCommandHelper.php	Adds $ref resolution for request bodies/properties and improves example extraction for usage generation.
src/Command/Api/ApiBaseCommand.php	Uses getParamType() to avoid direct access to missing type keys during casting.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Fixes warnings and improves requestBody parameter handling for generated API CLI commands, especially when OpenAPI requestBody and its properties are defined via $ref (notably for api:private-networks:create).

Changes:

• Resolve $ref at the requestBody level before processing request body parameters.
• Resolve $ref within individual requestBody schema properties to ensure a usable spec (incl. type) downstream.
• Extend example discovery to also read content.*.schema.example (in addition to content.*.example) and update PHPUnit coverage for the private networks create command.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.

File	Description
tests/phpunit/src/Commands/Api/ApiCommandTest.php	Adds coverage for $ref requestBody example extraction and the private-networks create usage expectation.
src/Command/Api/ApiCommandHelper.php	Adds $ref resolution for requestBodies and property schemas; falls back to schema.example for usage generation.
src/Command/Api/ApiBaseCommand.php	Uses getParamType() in castParamType() to avoid undefined type access.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[shriacquia]

@anujkaushal - could you review this today?