Série – Créer une API avec Symfony et API Platform

#2 Documentez efficacement votre API avec API Platform

Proposez une documentation détaillée à vos utilisateurs

7 oct. 2020 à 19:42 – 4min


Table des matières

Bonjour et bienvenue dans ce nouvel article consacré à la mise en place d'une API avec API Platform. Dans cet article, nous allons voir comment documenter efficacement votre API afin de faciliter son utilisation.

Documenter les opérations

Grâce à API Platform, il est tout à fait possible de documenter manuelle chacune de vos opérations. Tout cela se passe dans vos fichiers de configuration de vos entités :

Dans cet exemple, j'ai volontairement ajouté plusieurs fonctionnalités de manière assez anarchique, afin de pouvoir vous les présenter concrètement. 

Documenter le schéma d'entité

Les propriétés 

Il est possible de documenter chaque champ de votre entité. Ainsi, vos utilisateurs pourront comprendre comment fonctionne le schéma de vos entités et comment s'en servir correctement. Voyons un exemple : 

Si vous regardez la section "Schemas" en bas de votre documentation, vous verrez que l'entité Article est maintenant correctement documentée. Il est possible, et je vous encourage à le faire, d'ajouter des exemples et des descriptions sur chacun de vos champs. 

Exemple de documentation d'un Schema avec API Platform

Les paramètres

Si vous souhaitez décrire vos paramètres d'URL, par exemple pour l'opération GET /api/articles/{id}, ajoutez cette configuration :

Il est également possible de décrire le schéma du corps de vos requêtes, par exemple pour l'opération POST /api/articles

À ce stade, vous devrez manuellement ajouter le champ isPublished et publishedAt. Vous voudrez certainement les définir automatiquement lorsque vous persistez un nouvel article. Pour celà, je vous conseille de consulter mon article sur les LifecycleCallbacks de Doctrine

Utiliser d'autres formats de documentation

Pour le moment, nous utilisons SwaggerUI comme template de documentation. Mais il est tout à fait possible d'opter pour d'autres formats grâce à API Platform. Nous allons dans cet exemple ajouter la possibilité d'utiliser ReDoc comme format, en plus de SwaggerUI. 

ReDoc est une alternative à SwaggerUi, que je trouve personnellement plus lisible et concise, particulièrement lorsque l'API expose beaucoup d'opérations et de schémas différents. Néanmoins, il n'est pas possible de tester vos opérations directement depuis la documentation avec ReDoc. C'est pour cette raison que nous ne l'utiliserons pas pour la suite de ce cours, par soucis de simplicité, même si dans des conditions réelles, je vous conseille plutôt d'importer votre schéma OpenAPI dans une application telle que Postman pour tester votre API.

Je vous propose d'ailleurs d'aller faire un tour sur l'un de mes articles afin d'apprendre à tester efficacement votre API grâce à Postman :)

Rendez-vous dans votre fichier de configuration api_platform.yaml, puis ajoutez les lignes suivantes :

Actualisez votre documentation, puis cliquez sur ReDoc tout en bas à droite de la page. Voilà, vous avez la possibilité de proposer un nouveau type de documentation à vos utilisateurs !