From dc0205ffe39527882ed9cf86916a22f0dd97c84f Mon Sep 17 00:00:00 2001
From: cay89 <cay89@users.noreply.github.com>
Date: Fri, 22 May 2026 15:30:44 +0200
Subject: [PATCH 1/2] Add credential handling instructions for Swagger UI
 (#2285)

---
 core/openapi.md | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/core/openapi.md b/core/openapi.md
index 0f829740688..c29b020ed5d 100644
--- a/core/openapi.md
+++ b/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

From 7baceb4b7adf4b778449b2453a089ff40e0fdd6f Mon Sep 17 00:00:00 2001
From: soyuka <soyuka@users.noreply.github.com>
Date: Sat, 6 Jun 2026 08:34:49 +0200
Subject: [PATCH 2/2] docs(serialization): document element-type requirement
 for readableLink on collection getters

When readableLink: false is applied to a getter returning array, PropertyInfo
resolves array<mixed> and cannot determine the element class, causing the
relation to be embedded. Document the three remedies (PHPDoc @return,
ApiProperty nativeType, typed Doctrine collection) and link to #8179.
---
 core/serialization.md | 87 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/core/serialization.md b/core/serialization.md
index 82f21619a1f..7da6c3ba4c0 100644
--- a/core/serialization.md
+++ b/core/serialization.md
@@ -675,6 +675,93 @@ App\ApiResource\Person:
 
 </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