Skip to content

Commit fa3bd28

Browse files
vinceAmstoutzMickaelSchimpfnikophil
authored
Merge 4.0 into main (#2132)
* docs(openapi): add custom UI template override for Laravel (#2113) Added documentation on overriding the default OpenAPI UI template. * 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. * 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 <nikophil@gmail.com> * fix(openapi): resolve unsupported blade markdown types by hugoserver --------- Co-authored-by: MickaelSchimpf <122897940+MickaelSchimpf@users.noreply.github.com> Co-authored-by: Nicolas PHILIPPE <nikophil@gmail.com>
1 parent 5ac9eaa commit fa3bd28

File tree

3 files changed

+92
-5
lines changed

3 files changed

+92
-5
lines changed

‎core/content-negotiation.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,6 +196,19 @@ api_platform:
196196
myformat: ['application/vnd.myformat']
197197
```
198198

199+
You will also need to declare an encoder which supports the new format:
200+
201+
```yaml
202+
services:
203+
app.api-platform.myformat.encoder:
204+
class: ApiPlatform\Serializer\JsonEncoder
205+
arguments:
206+
$format: 'myformat'
207+
# The following lines are only needed if autoconfigure is disabled
208+
# tags:
209+
# - { name: 'serializer.encoder' }
210+
```
211+
199212
API Platform will automatically call the serializer with your defined format name as `format` parameter during the deserialization process (`myformat` in the example).
200213
It will then return the result to the client with the requested MIME type using its built-in responder.
201214
For non-standard formats, [a vendor, vanity or unregistered MIME type should be used](https://en.wikipedia.org/wiki/Media_type#Vendor_tree).

‎core/openapi.md

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -717,6 +717,10 @@ framework:
717717

718718
## Overriding the UI Template
719719

720+
You can extend the default UI Template using the Symfony and Laravel instructions below:
721+
722+
### Overriding the UI Template using Symfony
723+
720724
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:
721725

722726
```twig
@@ -732,6 +736,28 @@ As described [in the Symfony documentation](https://symfony.com/doc/current/temp
732736

733737
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.
734738

739+
### Overriding the UI Template using Laravel
740+
741+
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:
742+
743+
```html
744+
{# resources/views/swagger-ui.blade.php #}
745+
<!DOCTYPE html>
746+
<html>
747+
<head>
748+
<meta charset="UTF-8">
749+
<title>
750+
@if(isset($title))
751+
{{ $title }}
752+
@endif
753+
My custom template
754+
</title>
755+
{# ... #}
756+
</html>
757+
```
758+
759+
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.
760+
735761
## Compatibility Layer with Amazon API Gateway
736762

737763
[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).

‎core/serialization.md

Lines changed: 53 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,18 +49,51 @@ to limit the serialization depth.
4949
Just like other Symfony and API Platform components, the Serializer component can be configured using attributes, XML
5050
or YAML. Since attributes are easy to understand, we will use them in the following examples.
5151

52-
Note: if you aren't using the API Platform distribution, you will need to enable annotation support in the serializer configuration:
52+
> [!NOTE]
53+
> If you are not using the API Platform distribution, you need to enable annotation support in the serializer
54+
> configuration as outlined below, depending on your Symfony version.
55+
56+
#### Configuration for Symfony `<= 6.4`
57+
58+
##### General Case
59+
60+
Add the following configuration to your `framework.yaml` file:
5361

5462
```yaml
5563
# api/config/packages/framework.yaml
5664
framework:
5765
serializer: { enable_annotations: true }
5866
```
5967
60-
If you use [Symfony Flex](https://github.com/symfony/flex), just execute `composer req doctrine/annotations` and you are
61-
all set!
68+
##### Using Symfony Flex
69+
70+
If you use [Symfony Flex](https://github.com/symfony/flex) and Symfony `<= 6.4`, simply run the following command:
71+
72+
```console
73+
composer req doctrine/annotations
74+
```
75+
76+
You're all set!
77+
78+
#### Configuration for Symfony `>= 7.0`
79+
80+
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).
81+
82+
Update your configuration as follows:
83+
84+
```diff
85+
# api/config/packages/framework.yaml
86+
87+
framework:
88+
- serializer: { enable_annotations: true }
89+
+ serializer: { enable_attributes: true }
90+
```
91+
92+
#### Additional Syntax Configuration for All Versions
93+
94+
If you want to use YAML or XML for serialization, add the mapping path to the serializer configuration:
6295

63-
If you want to use YAML or XML, please add the mapping path in the serializer configuration:
96+
<code-selector>
6497

6598
```yaml
6699
# api/config/packages/framework.yaml
@@ -70,6 +103,21 @@ framework:
70103
paths: ['%kernel.project_dir%/config/serialization']
71104
```
72105

106+
```xml
107+
<!-- api/config/packages/framework.xml -->
108+
<framework>
109+
<!-- ... -->
110+
<serializer>
111+
<mapping>
112+
<path>%kernel.project_dir%/config/serialization</path>
113+
</mapping>
114+
</serializer>
115+
</framework>
116+
117+
```
118+
119+
</code-selector>
120+
73121
## Using Serialization Groups
74122

75123
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:
435483
```
436484

437485
In order to optimize such embedded relations, the default Doctrine state provider will automatically join entities on relations
438-
marked as [`EAGER`](https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/annotations-reference.html#manytoone).
486+
marked as [`EAGER`](https://www.doctrine-project.org/projects/doctrine-orm/en/current/reference/attributes-reference.html#manytoone).
439487
This avoids the need for extra queries to be executed when serializing the related objects.
440488

441489
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).

0 commit comments

Comments
 (0)