api-platform · vinceAmstoutz · Jan 15, 2025 · Jan 13, 2025 · Jan 13, 2025 · Jan 15, 2025
diff --git a/core/content-negotiation.md b/core/content-negotiation.md
@@ -196,6 +196,19 @@ api_platform:
     myformat: ['application/vnd.myformat']
 ```
 
+You will also need to declare an encoder which supports the new format:
+
+```yaml
+services:
+    app.api-platform.myformat.encoder:
+      class: ApiPlatform\Serializer\JsonEncoder
+      arguments:
+          $format: 'myformat'
+      # The following lines are only needed if autoconfigure is disabled
+      # tags:
+      #     - { name: 'serializer.encoder' }
+```
+
 API Platform will automatically call the serializer with your defined format name as `format` parameter during the deserialization process (`myformat` in the example).
 It will then return the result to the client with the requested MIME type using its built-in responder.
 For non-standard formats, [a vendor, vanity or unregistered MIME type should be used](https://en.wikipedia.org/wiki/Media_type#Vendor_tree).

diff --git a/core/openapi.md b/core/openapi.md
@@ -717,6 +717,10 @@ framework:
 
 ## Overriding the UI Template
 
+You can extend the default UI Template using the Symfony and Laravel instructions below:
+
+### Overriding the UI Template using Symfony
+
 As described [in the Symfony documentation](https://symfony.com/doc/current/templating/overriding.html), it's possible to override the Twig template that loads Swagger UI and renders the documentation:
 
 ```twig
@@ -732,6 +736,28 @@ As described [in the Symfony documentation](https://symfony.com/doc/current/temp
 
 You may want to copy the [one shipped with API Platform](https://github.com/api-platform/core/blob/main/src/Symfony/Bundle/Resources/views/SwaggerUi/index.html.twig) and customize it.
 
+### Overriding the UI Template using Laravel
+
+As described [in the Laravel documentation](https://laravel.com/docs/blade#extending-a-layout), it's possible to override the Blade template that loads Swagger UI and renders the documentation:
+
+```blade
+{# resources/views/swagger-ui.blade.php #}
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="UTF-8">
+    <title>
+        @if(isset($title)) 
+            {{ $title }} 
+        @endif
+        My custom template
+    </title>
+    {# ... #}
+</html>
+```
+
+You may want to copy the [one shipped with API Platform](https://github.com/api-platform/core/blob/main/src/Laravel/resources/views/swagger-ui.blade.php) and customize it.
+
 ## Compatibility Layer with Amazon API Gateway
 
 [AWS API Gateway](https://aws.amazon.com/api-gateway/) supports OpenAPI partially, but it [requires some changes](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-known-issues.html).

diff --git a/core/serialization.md b/core/serialization.md
@@ -49,18 +49,51 @@ to limit the serialization depth.
 Just like other Symfony and API Platform components, the Serializer component can be configured using attributes, XML
 or YAML. Since attributes are easy to understand, we will use them in the following examples.
 
-Note: if you aren't using the API Platform distribution, you will need to enable annotation support in the serializer configuration:
+> [!NOTE]
+> If you are not using the API Platform distribution, you need to enable annotation support in the serializer
+> configuration as outlined below, depending on your Symfony version.
+
+#### Configuration for Symfony `<= 6.4`
+
+##### General Case
+
+Add the following configuration to your `framework.yaml` file:
 
 ```yaml
 # api/config/packages/framework.yaml
 framework:
   serializer: { enable_annotations: true }
 ```
 
-If you use [Symfony Flex](https://github.com/symfony/flex), just execute `composer req doctrine/annotations` and you are
-all set!
+##### Using Symfony Flex
+
+If you use [Symfony Flex](https://github.com/symfony/flex) and Symfony `<= 6.4`, simply run the following command:
+
+```console
+composer req doctrine/annotations
+```
+
+You're all set!
+
+#### Configuration for Symfony `>= 7.0`
+
+If you are using Symfony >= 7.0, [annotations have been replaced by attributes](https://www.doctrine-project.org/2022/11/04/annotations-to-attributes.html).
+
+Update your configuration as follows:
+
+```diff
+# api/config/packages/framework.yaml
+
+framework:
+-  serializer: { enable_annotations: true }
++  serializer: { enable_attributes: true }
+```
+
+#### Additional Syntax Configuration for All Versions
+
+If you want to use YAML or XML for serialization, add the mapping path to the serializer configuration:
 
-If you want to use YAML or XML, please add the mapping path in the serializer configuration:
+<code-selector>
 
 ```yaml
 # api/config/packages/framework.yaml
@@ -70,6 +103,21 @@ framework:
       paths: ['%kernel.project_dir%/config/serialization']
 ```
 
+```xml
+<!-- api/config/packages/framework.xml -->
+<framework> 
+    <!-- ... -->
+    <serializer>
+        <mapping>
+            <path>%kernel.project_dir%/config/serialization</path>
+        </mapping>
+    </serializer>
+</framework>
+
+```
+
+</code-selector>
+
 ## Using Serialization Groups
 
 It is simple to specify what groups to use in the API system:
@@ -435,7 +483,7 @@ The generated JSON using previous settings is below:
 ```
 
 In order to optimize such embedded relations, the default Doctrine state provider will automatically join entities on relations
-marked as [`EAGER`](https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/annotations-reference.html#manytoone).
+marked as [`EAGER`](https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/attributes-reference.html#manytoone).
 This avoids the need for extra queries to be executed when serializing the related objects.
 
 Instead of embedding relations in the main HTTP response, you may want [to "push" them to the client using HTTP/2 server push](push-relations.md).