From c6670dcf1ec943b4b64a9f47da6661c35465da6e Mon Sep 17 00:00:00 2001 From: Vincent Amstoutz Date: Mon, 13 Jan 2025 16:04:07 +0100 Subject: [PATCH 1/3] docs(openapi): add custom UI template override for Laravel (#2113) Added documentation on overriding the default OpenAPI UI template. --- core/openapi.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/core/openapi.md b/core/openapi.md index 2a83ffff1a2..49d94f1f2c9 100644 --- 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 #} + + + + + + @if(isset($title)) + {{ $title }} + @endif + My custom template + + {# ... #} + +``` + +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). From 7d0224b691cefab42029c81636c1e5fa85facad0 Mon Sep 17 00:00:00 2001 From: Vincent Amstoutz Date: Mon, 13 Jan 2025 16:04:49 +0100 Subject: [PATCH 2/3] docs(serializer): deprecation of annotations and fix broken link (#2118) - Added detailed documentation about the deprecation of annotations in favor of attributes for Symfony >= 7.0. - Updated configuration examples for both annotation-based and attribute-based serializers. - Fixed a broken link to Symfony Flex documentation. --- core/serialization.md | 58 +++++++++++++++++++++++++++++++++++++++---- 1 file changed, 53 insertions(+), 5 deletions(-) diff --git a/core/serialization.md b/core/serialization.md index 400c0ce0d11..9527f248e8a 100644 --- a/core/serialization.md +++ b/core/serialization.md @@ -49,7 +49,15 @@ 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 @@ -57,10 +65,35 @@ 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: + ```yaml # api/config/packages/framework.yaml @@ -70,6 +103,21 @@ framework: paths: ['%kernel.project_dir%/config/serialization'] ``` +```xml + + + + + + %kernel.project_dir%/config/serialization + + + + +``` + + + ## 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). From 720f2008396f8f0d7400e839f6ddd927e34f0a36 Mon Sep 17 00:00:00 2001 From: Vincent Amstoutz Date: Wed, 15 Jan 2025 09:34:04 +0100 Subject: [PATCH 3/3] Merge 3.4 in 4.0 (#2127) * docs(validation): add missing hook (#1795) docs: add missing hook in validation.md for "Dynamic validation groups" * docs(content-negociation): document how to declare an encoder for custom format (#1797) --------- Co-authored-by: MickaelSchimpf <122897940+MickaelSchimpf@users.noreply.github.com> Co-authored-by: Nicolas PHILIPPE --- core/content-negotiation.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/core/content-negotiation.md b/core/content-negotiation.md index 2622f39dfa5..c0df55e27b5 100644 --- 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).