« Programmation PHP avec Symfony/API » : différence entre les versions
m <source> -> <syntaxhighlight> (phab:T237267) |
|||
Ligne 8 : | Ligne 8 : | ||
=== FOS REST === |
=== FOS REST === |
||
FOSRestBundle apporte des annotations pour créer des contrôleurs d'API<ref>https://github.com/FriendsOfSymfony/FOSRestBundle</ref>. Installation : |
FOSRestBundle apporte des annotations pour créer des contrôleurs d'API<ref>https://github.com/FriendsOfSymfony/FOSRestBundle</ref>. Installation : |
||
< |
<syntaxhighlight lang=bash> |
||
composer require "friendsofsymfony/rest-bundle" |
composer require "friendsofsymfony/rest-bundle" |
||
</syntaxhighlight> |
|||
</source> |
|||
Puis dans <u>config/packages/fos_rest.yaml</u> : |
Puis dans <u>config/packages/fos_rest.yaml</u> : |
||
< |
<syntaxhighlight lang=yaml> |
||
fos_rest: |
fos_rest: |
||
view: |
view: |
||
Ligne 21 : | Ligne 21 : | ||
- { path: '^/', prefer_extension: true, fallback_format: ~, priorities: [ 'html', '*/*'] } |
- { path: '^/', prefer_extension: true, fallback_format: ~, priorities: [ 'html', '*/*'] } |
||
- { path: ^/api, prefer_extension: true, fallback_format: json, priorities: [ json ] } |
- { path: ^/api, prefer_extension: true, fallback_format: json, priorities: [ json ] } |
||
</syntaxhighlight> |
|||
</source> |
|||
=== Doc === |
=== Doc === |
||
Toute API doit exposer sa documentation avec ses routes et leurs paramètres. NelmioApiDocBundle est un de générateur de documentation automatique à partir du code<ref>https://github.com/nelmio/NelmioApiDocBundle</ref>, qui permet en plus de tester en ligne. En effet, pour éviter de tester les API en copiant-collant leurs chemins dans une commande {{w|cURL}} ou dans des logiciels plus complets comme Postman<ref>https://www.postman.com/</ref>, on peut installer une interface graphique ergonomique qui allie documentation et test en ligne : |
Toute API doit exposer sa documentation avec ses routes et leurs paramètres. NelmioApiDocBundle est un de générateur de documentation automatique à partir du code<ref>https://github.com/nelmio/NelmioApiDocBundle</ref>, qui permet en plus de tester en ligne. En effet, pour éviter de tester les API en copiant-collant leurs chemins dans une commande {{w|cURL}} ou dans des logiciels plus complets comme Postman<ref>https://www.postman.com/</ref>, on peut installer une interface graphique ergonomique qui allie documentation et test en ligne : |
||
< |
<syntaxhighlight lang=bash> |
||
composer require "nelmio/api-doc-bundle" |
composer require "nelmio/api-doc-bundle" |
||
</syntaxhighlight> |
|||
</source> |
|||
Son URL se configure ensuite dans <u>routes/nelmio_api_doc.yml</u> : |
Son URL se configure ensuite dans <u>routes/nelmio_api_doc.yml</u> : |
||
< |
<syntaxhighlight lang=yaml> |
||
app.swagger_ui: |
app.swagger_ui: |
||
path: /api/doc |
path: /api/doc |
||
methods: GET |
methods: GET |
||
defaults: { _controller: nelmio_api_doc.controller.swagger_ui } |
defaults: { _controller: nelmio_api_doc.controller.swagger_ui } |
||
</syntaxhighlight> |
|||
</source> |
|||
A ce stade l'URL /api/doc affiche juste un lien ''NelmioApiDocBundle''. |
A ce stade l'URL /api/doc affiche juste un lien ''NelmioApiDocBundle''. |
||
Ligne 46 : | Ligne 46 : | ||
==== symfony/serializer ==== |
==== symfony/serializer ==== |
||
< |
<syntaxhighlight lang=bash> |
||
composer require "symfony/serializer" |
composer require "symfony/serializer" |
||
</syntaxhighlight> |
|||
</source> |
|||
==== jms/serializer-bundle ==== |
==== jms/serializer-bundle ==== |
||
< |
<syntaxhighlight lang=bash> |
||
composer require "jms/serializer-bundle" |
composer require "jms/serializer-bundle" |
||
</syntaxhighlight> |
|||
</source> |
|||
== Utilisation == |
== Utilisation == |
||
Ligne 60 : | Ligne 60 : | ||
Maintenant /api/doc affiche les méthodes des différents contrôleurs API. Voici un exemple : |
Maintenant /api/doc affiche les méthodes des différents contrôleurs API. Voici un exemple : |
||
< |
<syntaxhighlight lang=php> |
||
<?php |
<?php |
||
Ligne 83 : | Ligne 83 : | ||
} |
} |
||
} |
} |
||
</syntaxhighlight> |
|||
</source> |
|||
Maintenant dans /api/doc, cliquer sur /api/test, puis "Ty it out" pour exécuter la méthode de test. |
Maintenant dans /api/doc, cliquer sur /api/test, puis "Ty it out" pour exécuter la méthode de test. |
Version du 16 avril 2020 à 09:16
Installation
Pour créer une interface de programmation (API) REST avec Symfony, il existe plusieurs bibliothèques :
- API Platform[1], tout-en-un qui utilise les annotations des entités pour créer les APIs (donc pas besoin de créer des contrôleurs ou autres).
- Sinon il faut combiner plusieurs éléments : routeur, générateur de doc en ligne et sérialiseur. En voici un exemple :
FOS REST
FOSRestBundle apporte des annotations pour créer des contrôleurs d'API[2]. Installation :
composer require "friendsofsymfony/rest-bundle"
Puis dans config/packages/fos_rest.yaml :
fos_rest:
view:
view_response_listener: true
format_listener:
rules:
- { path: '^/', prefer_extension: true, fallback_format: ~, priorities: [ 'html', '*/*'] }
- { path: ^/api, prefer_extension: true, fallback_format: json, priorities: [ json ] }
Doc
Toute API doit exposer sa documentation avec ses routes et leurs paramètres. NelmioApiDocBundle est un de générateur de documentation automatique à partir du code[3], qui permet en plus de tester en ligne. En effet, pour éviter de tester les API en copiant-collant leurs chemins dans une commande cURL ou dans des logiciels plus complets comme Postman[4], on peut installer une interface graphique ergonomique qui allie documentation et test en ligne :
composer require "nelmio/api-doc-bundle"
Son URL se configure ensuite dans routes/nelmio_api_doc.yml :
app.swagger_ui:
path: /api/doc
methods: GET
defaults: { _controller: nelmio_api_doc.controller.swagger_ui }
A ce stade l'URL /api/doc affiche juste un lien NelmioApiDocBundle.
Sérialiseur
Enfin pour la sérialisation, on distingue plusieurs solutions :
- symfony/serializer, qui donne des contrôleurs
extends AbstractFOSRestController
et des méthodes aux annotations@Rest\Post()
[5]. - jms/serializer-bundle, avec des contrôleurs
extends RestController
et des méthodes aux annotations@ApiDoc()
. - Le service
fos_rest.service.serializer
.
symfony/serializer
composer require "symfony/serializer"
jms/serializer-bundle
composer require "jms/serializer-bundle"
Utilisation
Avec le triplet de bibliothèques
Maintenant /api/doc affiche les méthodes des différents contrôleurs API. Voici un exemple :
<?php
namespace App\Controller;
use FOS\RestBundle\Controller\AbstractFOSRestController;
use FOS\RestBundle\View\View;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;
class APIController extends AbstractFOSRestController
{
/**
* Test the API
* @Route("/api/test", methods={"GET"})
* @param Request $request
* @return View
*/
public function testAction(Request $request): View
{
return View::create('ok');
}
}
Maintenant dans /api/doc, cliquer sur /api/test, puis "Ty it out" pour exécuter la méthode de test.