Fix ArrayDescriber splitting arrayKey() union into anyOf [array, object]

When TypeInfo resolves `array<T>` (single generic parameter, no explicit
key type), the key defaults to `arrayKey()` which is `union(int, string)`.
ArrayDescriber was splitting this into separate `array<int, T>` and
`array<string, T>` types, producing `anyOf: [{type: array}, {type: object}]`
in the OpenAPI schema. This is incorrect — `array<T>` in PHP means a
JSON array, not "either array or object".

Additionally, when a Traversable object is used as a generic parameter
(e.g. `list<MyIterableClass>`), StringTypeResolver wraps it in
CollectionType(ObjectType) with no key/value type info. ArrayDescriber
then describes this as `array<unknown>`. The fix detects when the wrapped
type is an ObjectType and delegates to the chain so ClassDescriber can
create a proper `$ref`.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gnutix

src/TypeDescriber/ArrayDescriber.php

@@ -14,6 +14,7 @@
 use OpenApi\Annotations\Schema;
 use Symfony\Component\TypeInfo\Type;
 use Symfony\Component\TypeInfo\Type\CollectionType;
+use Symfony\Component\TypeInfo\TypeIdentifier;
 
 /**
  * @implements TypeDescriberInterface<CollectionType>
@@ -30,6 +31,30 @@ public function describe(Type $type, Schema $schema, array $context = []): void
             throw new \LogicException('This describer only supports '.CollectionType::class.' with '.Type\UnionType::class.' as key type.');
         }
 
+        // When the key type is arrayKey() (int|string union), the collection has
+        // no explicit key type (e.g. `array<T>` in PHPDoc). Treat as a JSON array
+        // rather than splitting into anyOf: [array, object].
+        $keyTypes = $type->getCollectionKeyType()->getTypes();
+        if (2 === \count($keyTypes)
+            && $keyTypes[0] instanceof Type\BuiltinType && TypeIdentifier::INT === $keyTypes[0]->getTypeIdentifier()
+            && $keyTypes[1] instanceof Type\BuiltinType && TypeIdentifier::STRING === $keyTypes[1]->getTypeIdentifier()
+        ) {
+            // When a Traversable object is used as a generic parameter
+            // (e.g. `list<MyTraversableClass>`), StringTypeResolver wraps it in
+            // CollectionType(ObjectType) with no key/value type info. Unwrap it
+            // so ClassDescriber can create a proper $ref.
+            $wrappedType = $type->getWrappedType();
+            if ($wrappedType instanceof Type\ObjectType) {
+                $this->describer->describe($wrappedType, $schema, $context);
+
+                return;
+            }
+
+            $this->describer->describe(Type::list($type->getCollectionValueType()), $schema, $context);
+
+            return;
+        }
+
         $arrayTypes = array_map(
             static fn (Type $keyType): Type => Type::array($type->getCollectionValueType(), $keyType),
             $type->getCollectionKeyType()->getTypes()

tests/TypeDescriber/ArrayDescriberTest.php

@@ -12,6 +12,7 @@
 namespace Nelmio\ApiDocBundle\Tests\TypeDescriber;
 
 use Nelmio\ApiDocBundle\TypeDescriber\ArrayDescriber;
+use Nelmio\ApiDocBundle\TypeDescriber\TypeDescriberInterface;
 use OpenApi\Annotations\Schema;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\TypeInfo\Type;
@@ -47,4 +48,46 @@ public static function provideInvalidCollectionTypes(): \Generator
         yield [Type::list()];
         yield [Type::dict()];
     }
+
+    /**
+     * When the key type is arrayKey() (int|string union), the describer should
+     * treat the collection as a list rather than splitting into anyOf [array, object].
+     */
+    public function testArrayKeyUnionIsTreatedAsList(): void
+    {
+        $innerDescriber = $this->createMock(TypeDescriberInterface::class);
+        $innerDescriber->expects(self::once())
+            ->method('describe')
+            ->with(self::callback(static function (Type $type): bool {
+                // Should delegate a list(string) — i.e. CollectionType with int key and string value
+                return $type instanceof CollectionType
+                    && $type->isList()
+                    && 'string' === (string) $type->getCollectionValueType();
+            }));
+
+        $this->describer->setDescriber($innerDescriber);
+
+        // array<string> is resolved by TypeInfo as CollectionType with arrayKey() union key
+        $type = Type::array(Type::string());
+        $this->describer->describe($type, new Schema([]));
+    }
+
+    /**
+     * When a Traversable object is auto-wrapped in CollectionType(ObjectType),
+     * the describer should unwrap it and delegate the ObjectType directly.
+     */
+    public function testTraversableObjectIsUnwrapped(): void
+    {
+        $objectType = Type::object(\ArrayObject::class);
+        // Simulate what StringTypeResolver does: wrap in CollectionType(ObjectType)
+        $collectionType = new CollectionType($objectType);
+
+        $innerDescriber = $this->createMock(TypeDescriberInterface::class);
+        $innerDescriber->expects(self::once())
+            ->method('describe')
+            ->with(self::identicalTo($objectType));
+
+        $this->describer->setDescriber($innerDescriber);
+        $this->describer->describe($collectionType, new Schema([]));
+    }
 }