« Programmation PHP avec Symfony/API » : différence entre les versions
m <source> -> <syntaxhighlight> (phab:T237267) |
Aucun résumé des modifications |
||
Ligne 1 : | Ligne 1 : | ||
<noinclude>{{PHP}}</noinclude> |
<noinclude>{{PHP}}</noinclude> |
||
⚫ | |||
Pour créer une {{w|interface de programmation}} (API) {{w|Representational state transfer|REST}} avec Symfony, il existe plusieurs bibliothèques : |
Pour créer une {{w|interface de programmation}} (API) {{w|Representational state transfer|REST}} avec Symfony, il existe plusieurs bibliothèques : |
||
* API Platform<ref>https://api-platform.com/</ref>, 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). |
* API Platform<ref>https://api-platform.com/</ref>, 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). Par défaut il permet de sérialiser les flux en JSON (dont JSON-LD, JSON-HAL, JSON:API), XML (dont HTML), CSV et YAML<ref>https://api-platform.com/docs/core/content-negotiation/</ref>. |
||
* Sinon il faut combiner plusieurs éléments : routeur, générateur de doc en ligne et sérialiseur. |
* Sinon il faut combiner plusieurs éléments : routeur, générateur de doc en ligne et sérialiseur. |
||
== API Platform == |
|||
⚫ | |||
<syntaxhighlight lang=bash> |
|||
composer require api |
|||
</syntaxhighlight> |
|||
== Utilisation == |
|||
API Platform se configure par des annotations dans les entités. |
|||
=== Annotations === |
|||
==== MaxDepth() ==== |
|||
Définit le niveau de sérialisation d'un élément lié. Par exemple, si un client a plusieurs contrats et que ses contrats ont plusieurs produits, un ''MaxDepth(1)'' sur l'attribut ''client->contrat'' fera que la liste des clients comprendra tous les contrats mais pas leurs produits. |
|||
⚫ | |||
=== Installation === |
|||
==== 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> |
<syntaxhighlight lang=bash> |
||
Ligne 23 : | Ligne 37 : | ||
</syntaxhighlight> |
</syntaxhighlight> |
||
=== 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> |
<syntaxhighlight lang=bash> |
||
Ligne 39 : | Ligne 53 : | ||
A ce stade l'URL /api/doc affiche juste un lien ''NelmioApiDocBundle''. |
A ce stade l'URL /api/doc affiche juste un lien ''NelmioApiDocBundle''. |
||
=== Sérialiseur === |
==== Sérialiseur ==== |
||
Enfin pour la {{wt|sérialisation}}, on distingue plusieurs solutions : |
Enfin pour la {{wt|sérialisation}}, on distingue plusieurs solutions : |
||
* symfony/serializer, qui donne des contrôleurs <code>extends AbstractFOSRestController</code> et des méthodes aux annotations <code>@Rest\Post()</code><ref>https://www.thinktocode.com/2018/03/26/symfony-4-rest-api-part-1-fosrestbundle/</ref>. |
* symfony/serializer, qui donne des contrôleurs <code>extends AbstractFOSRestController</code> et des méthodes aux annotations <code>@Rest\Post()</code><ref>https://www.thinktocode.com/2018/03/26/symfony-4-rest-api-part-1-fosrestbundle/</ref>. |
||
Ligne 45 : | Ligne 59 : | ||
* Le service <code>fos_rest.service.serializer</code>. |
* Le service <code>fos_rest.service.serializer</code>. |
||
==== symfony/serializer ==== |
===== symfony/serializer ===== |
||
<syntaxhighlight lang=bash> |
<syntaxhighlight lang=bash> |
||
composer require "symfony/serializer" |
composer require "symfony/serializer" |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
==== jms/serializer-bundle ==== |
===== jms/serializer-bundle ===== |
||
<syntaxhighlight lang=bash> |
<syntaxhighlight lang=bash> |
||
composer require "jms/serializer-bundle" |
composer require "jms/serializer-bundle" |
||
</syntaxhighlight> |
</syntaxhighlight> |
||
== Utilisation == |
=== Utilisation === |
||
⚫ | |||
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 : |
||
Version du 9 juin 2020 à 17:46
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). Par défaut il permet de sérialiser les flux en JSON (dont JSON-LD, JSON-HAL, JSON:API), XML (dont HTML), CSV et YAML[2].
- Sinon il faut combiner plusieurs éléments : routeur, générateur de doc en ligne et sérialiseur.
API Platform
Installation
composer require api
Utilisation
API Platform se configure par des annotations dans les entités.
Annotations
MaxDepth()
Définit le niveau de sérialisation d'un élément lié. Par exemple, si un client a plusieurs contrats et que ses contrats ont plusieurs produits, un MaxDepth(1) sur l'attribut client->contrat fera que la liste des clients comprendra tous les contrats mais pas leurs produits.
Triplet de bibliothèques
Installation
FOS REST
FOSRestBundle apporte des annotations pour créer des contrôleurs d'API[3]. 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[4], 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[5], 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()
[6]. - 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
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.