Exploiter OpenAPI (2ème partie) — Automatiser et tester son API
Dans l’article précédent consacré à OpenAPI, nous avons partagé notre utilisation de ces spécifications pour documenter une API REST, et les problèmes que nous avons rencontrés (augmentation rapide du nombre de endpoints à documenter, difficulté de maintenance…) et les solutions que nous avons trouvées (utiliser le mécanisme de références décrit dans les spécification pour découper notre schéma en petits fichiers plus faciles à gérer).
Dans ce second article je vais expliquer les autres utilisations d’OpenAPI que nous avons explorées et mises en place.
Automatiser
Nos ingénieurs backend pensaient que nous pourrions aller encore plus loin avec ce schéma OpenAPI. Notre approche basée sur la Clean Architecture génère beaucoup de fichiers, alors pourquoi ne pas utiliser le schéma OpenAPI pour générer des contrôleurs à la volée, pour effectuer la validation des requêtes et construire des réponses sans ajouter de fichiers de code inutiles à chaque fois (oui, on parle de vous les POPOs/DTOs)? Nous pourrions alors concentrer nos efforts sur le code métier. C’est ce qui a été rapidement prototypé puis adopté, et cela a vraiment changé notre manière de travailler.
Il y a deux éléments principaux dans l’implémentation, d’abord nous avons un hook dans une Symfony compiler pass, nous utilisons openapi-psr7-validator pour mettre en cache quelques validateurs de request et les routes. Ensuite, nous avons une classe contrôleur générique, OpenApiController, qui mappe chaque route dans le schéma à une classe de use-case, en utilisant le mécanisme d’extension, nous avons appelé notre propriété “x-usecase”, et elle contient le FQDN de la classe PHP du use-case correspondant à chaque route définie dans le schéma. Il nous reste quelques routes legacy qui ne sont pas couvertes par OpenAPI, il y a donc un peu de plomberie pour détecter ces cas.
Non seulement nous pouvons maintenant documenter notre API, mais ce schéma est également utilisé au runtime pour nous faciliter la vie, et ça nous permet d’écrire beaucoup moins de code boilerplate !
Au delà de la documentation: API Tester
À un moment donné, nous avons pensé que nous pouvions tirer encore plus parti de notre documentation API. Pourquoi ne pas générer automatiquement des tests à partir du schéma OpenAPI pour ajouter une suite de tests conséquente à nos tests unitaires et d’intégration déjà existants ? Une petite équipe a rapidement mis au point ce qui est devenu Api Tester.
Cet outil codé en PHP charge notre schéma OpenAPI et génère automatiquement des milliers de tests pour tester notre API avec des cas nominaux (basés sur les exemples de la documentation) et des tests aléatoires pour garantir le comportement et vérifier tous les validateurs et la sécurité. Encore une fois, OpenAPI nous apportait beaucoup.
Nous envisageons de rendre Api Tester open-source dans un futur proche, si vous voulez en savoir plus sur le projet, nos développeurs ont présenté le projet à l’AFUP Day Lille 2023, et ont participé à un épisode de Product Crew webcast :“Gagner en productivité et en clarté d’Api”.
Les outils
Nos outils:
- php-openapi (que nous remplacerons peut être par ce fork qui supporte: OpenAPI 3.1), nous l’utilisons pour le lint et au runtime.
- spectral, en version CLI pour linter notre doc avec un custom ruleset
- redocly pour générer une version HTML de la doc
- swagger-cli que nous utilisons pour une première passe de lint, et ensuite pour reconstruire un schéma OpenAPI monolithique que nous pouvons alors passer aux outils que ne gèrent pas bien les documentations à fichiers multiples.
- openapi-psr7-validator encore un très bon package de thephpleague, pour valider nos requêtes.
Nous avons récemment découvert la librairie Janephp de chez JoliCode, qui permet de générer une API REST facilement à partir d’un schéma OpenAPI, ça peut vous aider sur votre projet.
Réflexions
En cours de route, nous avons rencontré de nombreux problèmes, mais nous avons souvent découvert que nous n’étions pas les seuls. En naviguant à travers d’innombrables fils de discussion sur GitHub, nous avons fini par avoir l’impression que les spécifications OpenAPI étaient formidables, avec une communauté ouverte aux demandes, mais que l’écosystème était vraiment en retard, surtout en ce qui concerne PHP. Plus de trois ans après la sortie de OpenAPI 3.1 en avril 2021, qui apporte de nombreuses fonctionnalités intéressantes, les outils tiers prenant en charge cette version ne sont pas légion. Vous rencontrerez les mêmes noms d’ingénieurs dans de nombreuses discussions différentes (bravo à eux), et il semble que le développement de plusieurs dépôts largement utilisés ne soit plus très actifs, ce qui incite les développeurs à créer des forks. Mais c’est open source, vous pouvez donc contribuer. Des sites comme https://openapi.tools/ sont très pratiques pour trouver des outils et vérifier leur prise en charge des spécifications.
La suite : API-First design
Cette refonte du schéma OpenAPI en valait la peine. Nous pouvons maintenant valider la création des routes de l’API, partager des composants et avoir un historique Git bien plus lisible, créer des mocks, utiliser la définition OpenApi même dans le projet frontend. Nos projets futurs incluent davantage de règles personnalisées de linting et des étapes supplémentaires de CI concernant la validation et la détection de breaking changes dans l’API. Nous travaillons toujours sur notre projet Api Tester.
Cependant, quelques mises à jour seront peut-être nécessaires pour simplifier l’architecture des dossiers et fichiers, car certains développeurs pensent que nous sommes allés un peu trop loin. Il y a un compromis à faire entre la réutilisabilité et la facilité d’utilisation.
Gérer le versionnage de l’API est également à l’horizon, mais c’est un sujet qui fait débat.
Le changement majeur est l’adoption d‘une approche de conception API-First, que nous faisons déjà partiellement, mais qui doit être formalisée dans des processus standardisés. Cette question pourra faire l’objet d’un futur article.
TL;DR;
Les spécifications OpenAPI et les librairies qui les supportent peuvent être utilisées dans des pré-processeurs et au runtime pour générer des contrôleurs, validateurs et view models à la volée. Nous avons aussi développé un outil sur mesure, Api-Tester, pour générer automatiquement des suites de tests à partir de notre documentation.
