docs(serialization): document element-type requirement for readableLink on collection getters

core/openapi.md

@@ -924,6 +924,32 @@ return [
 > **must** be set according to the
 > [OpenID Connect specification](https://openid.net/specs/openid-connect-core-1_0.html).
 
+## Sending Credentials with Swagger UI Requests
+
+When your API is deployed behind a proxy that uses cookie-based authentication (e.g. Cloudflare
+Access), Swagger UI's requests may be rejected because the authentication cookie is not forwarded by
+default. Enabling `withCredentials` adds a `requestInterceptor` to SwaggerUIBundle that sets
+`credentials: 'include'` on every outgoing request, ensuring cookies are sent alongside token and
+CORS requests.
+
+### Sending Credentials with Swagger UI Requests using Symfony
+
+> [!NOTE] This feature is only available with Laravel. You're welcome to contribute the Symfony
+> implementation [on GitHub](https://github.com/api-platform/core).
+
+### Sending Credentials with Swagger UI Requests using Laravel
+
+```php
+<?php
+// config/api-platform.php
+return [
+    // ...
+    'swagger_ui' => [
+        'with_credentials' => true,
+    ],
+];
+```
+
 ## Info Object
 
 The [info object](https://swagger.io/specification/#info-object) provides metadata about the API

core/serialization.md

@@ -675,6 +675,93 @@
 
 </code-selector>
 
+### Collection Getters and readableLink
+
+When `readableLink: false` is set on a property whose getter returns a bare `array` (no element type),
+the Symfony PropertyInfo component resolves the type as `array<mixed>`. Because the element class is
+unknown, API Platform cannot determine that the items are API resources and falls back to embedding
+them instead of serializing them as IRIs.
+
+This is a configuration issue, not a bug. Provide the element type using one of the following
+approaches.
+
+**PHPDoc `@return` annotation**
+
+```php
+<?php
+// api/src/Entity/Brand.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+#[ApiResource]
+class Brand
+{
+    /** @return Car[] */
+    #[ApiProperty(readableLink: false)]
+    public function getCars(): array
+    {
+        return $this->cars->getValues();
+    }
+}
+```
+
+**`ApiProperty` `nativeType` parameter (API Platform >= 4.2)**
+
+```php
+<?php
+// api/src/Entity/Brand.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use Doctrine\ORM\Mapping as ORM;
+use Symfony\Component\TypeInfo\Type;
+
+#[ORM\Entity]
+#[ApiResource]
+class Brand
+{
+    #[ApiProperty(readableLink: false, nativeType: Type::list(Type::object(Car::class)))]
+    public function getCars(): array
+    {
+        return $this->cars->getValues();
+    }
+}
+```
+
+**Typed Doctrine collection**
+
+Return `Collection<int, Car>` instead of a plain `array`. PropertyInfo reads the generic type parameter
+and resolves the element class automatically.
+
+```php
+<?php
+// api/src/Entity/Brand.php
+namespace App\Entity;
+
+use ApiPlatform\Metadata\ApiProperty;
+use ApiPlatform\Metadata\ApiResource;
+use Doctrine\Common\Collections\Collection;
+use Doctrine\ORM\Mapping as ORM;
+
+#[ORM\Entity]
+#[ApiResource]
+class Brand
+{
+    #[ApiProperty(readableLink: false)]
+    public function getCars(): Collection
+    {
+        return $this->cars;
+    }
+}
+```
+
+For more details see [#8179](https://github.com/api-platform/core/issues/8179).
+
 ### Plain Identifiers for Symfony
 
 Instead of sending an IRI to set a relation, you may want to send a plain identifier. To do so, you