{"id":557,"date":"2016-04-11T19:26:42","date_gmt":"2016-04-11T18:26:42","guid":{"rendered":"http:\/\/louis.hatier.me\/blog\/?p=557"},"modified":"2021-03-05T22:23:08","modified_gmt":"2021-03-05T21:23:08","slug":"developper-api-rest-symfony-3","status":"publish","type":"post","link":"https:\/\/louis.hatier.me\/blog\/developper-api-rest-symfony-3\/","title":{"rendered":"D\u00e9velopper une API REST avec Symfony 3"},"content":{"rendered":"

\"Logo<\/a>Symfony (2 et 3) permet de publier tr\u00e8s facilement une API REST<\/strong> \u00e0 l\u2019aide de diff\u00e9rents bundles<\/em>.
\nCette API peut \u00eatre \u00e9galement fourni d\u2019une documentation g\u00e9n\u00e9r\u00e9e dynamiquement.<\/p>\n

L\u2019id\u00e9e est de cr\u00e9er une API REST simple, qui met \u00e0 disposition une liste d\u2019utilisateurs et de commentaires.
\nCommen\u00e7ons par g\u00e9n\u00e9rer un nouveau projet.<\/p>\n

<\/p>\n

cd \/var\/www\/\nsymfony new symfony-rest\ncd symfony-rest\/\n<\/code><\/pre>\n
Les bundles qui vont nous permettre d\u2019avoir une API fonctionnelle sont les suivants : FOSRestBundle<\/strong> et JMSSerializerBundle<\/strong>.
\nIl faut donc les ajouter via Composer<\/em> et les renseigner dans le tableau de la fonction registerBundles<\/code> du fichier app\/AppKernel.php<\/code>.<\/p>\n
composer require friendsofsymfony\/rest-bundle\ncomposer require jms\/serializer-bundle\n<\/code><\/pre>\n
new FOS\\RestBundle\\FOSRestBundle(),\nnew JMS\\SerializerBundle\\JMSSerializerBundle(),\n<\/code><\/pre>\n
Nous allons ensuite d\u00e9finir les param\u00e8tres du bundle FOSRestBundle dans le fichier app\/config\/config.yml<\/code>.<\/p>\n
# FOSRestBundle\nfos_rest:\n    param_fetcher_listener: true\n    body_listener: true\n    format_listener: true\n    view:\n        view_response_listener: 'force'\n        formats:\n            xml: true\n            json : true\n        templating_formats:\n            html: true\n        force_redirects:\n            html: true\n        failed_validation: HTTP_BAD_REQUEST\n        default_engine: twig\n    routing_loader:\n        default_format: json\n<\/code><\/pre>\n
Il nous reste \u00e0 d\u00e9finir le routing dans un fichier s\u00e9par\u00e9.
\nD\u00e9claration de l\u2019import du nouveau fichier dans app\/config\/routing.yml<\/code>, en pr\u00e9fixant l\u2019url par \u00ab\u00a0\/api\/\u00a0\u00bb<\/p>\n
api:\n    resource: api_routes.yml\n    type: rest\n    prefix: \/api\/\n<\/code><\/pre>\n
Contenu du fichier app\/config\/api_routes.yml<\/code> :<\/p>\n
users:\n    resource: AppBundle\\Controller\\UsersController\n    type:     rest\n\ncomments:\n    resource: AppBundle\\Controller\\CommentsController\n    type:     rest\n<\/code><\/pre>\n
Il nous faut cr\u00e9er une entity User et son repository, avec les champs dont vous avez besoin (nom, email, etc.).
\nPuis \u00e9crire le contenu de nos controllers, voici un exemple avec UsersController.php<\/code><\/p>\n
namespace AppBundle\\Controller;\n\nuse AppBundle\\Entity\\User;\nuse Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller;\n\nclass UsersController extends Controller\n{\n    \/**\n     * @return array\n     *\/\n    public function getUsersAction()\n    {\n        $em = $this->getDoctrine()->getManager();\n        $users = $em->getRepository('AppBundle:User')->findAll();\n\n        return array('users' => $users);\n    }\n\n    \/**\n     * @param User $user\n     * @return array\n     *\/\n    public function getUserAction(User $user)\n    {\n        return array('user' => $user);\n    }\n}\n<\/code><\/pre>\n
Ce bout de code nous permet de mettre \u00e0 disposition la liste des utilisateurs, ou bien un utilisateur pr\u00e9cis.
\nEn acc\u00e9dant \u00e0 http:\/\/localhost\/symfony-rest\/api\/users, l\u2019API REST retourne une collection d\u2019utilisateurs au format JSON.
\nVous pouvez avoir cette m\u00eame liste au format XML en suffixant l’URL avec \u00ab\u00a0.xml\u00a0\u00bb.
\nEn appelant URL suivante http:\/\/localhost\/symfony-rest\/api\/users\/1, le serveur retournera l\u2019utilisateur d\u00e9fini par l\u2019identifiant 1.<\/p>\n
{\n    \"users\": [\n        {\n            \"id\": 1,\n            \"email\": \"jdoe@domain.com\",\n            \"name\": \"John Doe\",\n            \"password\": \"449bf6759f52bc0d1b7953f9fc2aaf32\"\n        },\n        {\n            \"id\": 2,\n            \"email\": \"jdalton@domain.com\",\n            \"name\": \"Joe Dalton\",\n            \"password\": \"04bd53ec196f6de5101ab3a56f12d0a6\"\n        }\n    ]\n}\n<\/code><\/pre>\n
{\n    \"user\": {\n        \"id\": 1,\n        \"email\": \"jdoe@domain.com\",\n        \"name\": \"John Doe\",\n        \"password\": \"449bf6759f52bc0d1b7953f9fc2aaf32\"\n    }\n}\n<\/code><\/pre>\n
Par d\u00e9faut l\u2019API retourne tous les champs de notre entity. Vous avez la possibilit\u00e9 de pr\u00e9ciser soit par inclusion, soit par exclusion, les champs que vous souhaitez envoyer.
\nExemple dans notre cas en excluant le champ password :<\/p>\n
namespace AppBundle\\Entity;\n\nuse Doctrine\\ORM\\Mapping as ORM;\nuse JMS\\Serializer\\Annotation\\ExclusionPolicy;\nuse JMS\\Serializer\\Annotation\\Exclude;\nuse Doctrine\\Common\\Collections\\ArrayCollection;\n\n\/**\n * User\n *\n * @ORM\\Table(name=\"User\")\n * @ORM\\Entity(repositoryClass=\"AppBundle\\Repository\\UserRepository\")\n * @ExclusionPolicy(\"none\")\n *\/\nclass User\n{\n    \/**\n     * @var int\n     *\n     * @ORM\\Column(name=\"id\", type=\"integer\")\n     * @ORM\\Id\n     * @ORM\\GeneratedValue(strategy=\"AUTO\")\n     *\/\n    private $id;\n\n    \/**\n     * @var string\n     *\n     * @ORM\\Column(name=\"name\")\n     *\/\n    private $name;\n\n    \/**\n     * @var string\n     *\n     * @ORM\\Column(name=\"email\")\n     *\/\n    private $email;\n\n    \/**\n     * @var string\n     *\n     * @ORM\\Column(name=\"password\")\n     * @Exclude\n     *\/\n    private $password;\n\n    \/\/......\n<\/code><\/pre>\n
Il nous reste maintenant \u00e0 mettre \u00e0 disposition une documentation pour les personnes qui voudraient \u00e9ventuellement utiliser notre API.<\/p>\n
Pour cela nous allons utiliser le bundle NelmioApiDocBundle <\/strong>qui se base sur l\u2019outil Swagger<\/a> pour g\u00e9n\u00e9rer une documentation pratique et lisible.
\nDe notre c\u00f4t\u00e9, il faudra renseigner les informations utiles \u00e0 la documentation dans le PHPDoc<\/em> de chaque fonction de nos controllers.<\/p>\n
Dans un premier temps il faut ajouter le bundle \u00e0 notre configuration et le param\u00e9trer.<\/p>\n
composer require nelmio\/api-doc-bundle\n<\/code><\/pre>\n
On l’ajoute au fichier app\/AppKernel.php<\/code><\/p>\n
new NelmioApiDocBundleNelmioApiDocBundle(),\n<\/code><\/pre>\n
Petite ligne de configuration dans le fichier app\/config\/config.yml<\/code><\/p>\n
nelmio_api_doc: ~\n<\/code><\/pre>\n
Et enfin le routing qui va bien : app\/config\/routing.yml<\/code><\/p>\n
NelmioApiDocBundle:\n    resource: \"@NelmioApiDocBundle\/Resources\/config\/routing.yml\"\n    prefix:   \/api\/doc\n<\/code><\/pre>\n
Voici maintenant \u00e0 quoi ressemble le PHPDoc de nos fonctions dans UsersController.php<\/code>.<\/p>\n
namespace AppBundle\\Controller;\n\nuse AppBundle\\Entity\\User;\nuse Symfony\\Bundle\\FrameworkBundle\\Controller\\Controller;\nuse Nelmio\\ApiDocBundle\\Annotation\\ApiDoc;\n\nclass UsersController extends Controller\n{\n    \/**\n     * Cette fonction retourne tous les utilisateurs\n     * Possibilit\u00e9 de d\u00e9crire la fonction plus en d\u00e9tails\n     *\n     * @ApiDoc(\n     *  resource=true,\n     *  description=\"Retourne les utilisateurs\"\n     * )\n     *\n     * @return array\n     *\/\n    public function getUsersAction()\n    {\n        $em = $this->getDoctrine()->getManager();\n        $users = $em->getRepository('AppBundle:User')->findAll();\n\n        return array('users' => $users);\n    }\n\n    \/**\n     * Cette fonction retourne un utilisateur\n     * Possibilit\u00e9 de d\u00e9crire la fonction plus en d\u00e9tails\n     *\n     * @ApiDoc(\n     *  description=\"Retourne un utilisateur\",\n     *  parameters={\n     *      {\"name\"=\"id\", \"dataType\"=\"integer\", \"required\"=true, \"description\"=\"identifiant de l'utilisateur\"}\n     *  }\n     * )\n     *\n     * @param User $user\n     * @return array\n     *\/\n    public function getUserAction(User $user)\n    {\n        return array('user' => $user);\n    }\n}\n<\/code><\/pre>\n
Pour cr\u00e9er des fonctionnalit\u00e9s POST\/DELETE\/PUT, qui sont les verbes<\/em> qui caract\u00e9risent une application RESTful, il suffit de pr\u00e9fixer le nom de votre fonction comme ceci : postUserAction(), putUserAction() etc.<\/p>\n
D\u00e9sormais, vous pouvez partager la documentation de votre API \u00e0 cette adresse http:\/\/localhost\/symfony-rest\/api\/doc.<\/p>\n
Voici \u00e0 quoi ressemble le rendu final :<\/p>\n
\"Documentation<\/a><\/p>\n
Une \u00e9tape suppl\u00e9mentaire sera de g\u00e9rer une identification utilisateur s\u00e9curis\u00e9e via OAuth2.
\nPeut-\u00eatre dans un prochain billet :)<\/p>\n
\"Share<\/a>