Aujourd’hui les APIs sont partout, les documenter correctement est un prérequis pour qu’elles soient utilisées correctement. Nous avons fait le choix d’utiliser OpenAPI qui s’est imposé comme un standard dans la documentation d’API ces dernières années.
L’écosystème autour d’OpenAPI est très riche avec de nombreux générateurs (code et documentation). L’avantage de ce format est qu’il est très technique. Dans l’écosystème de PHP, nous n’avons pas trouvé d’outils pour nous aider directement à fiabiliser cette documentation, c’est là qu’est né Raven: https://github.com/CHStudio/raven/.
Combiné à un système d’intégration continue, il détecte les erreurs et nous laisse les résoudre avant de passer en production. La documentation permet de vérifier que l’API fonctionne et l’API permet de vérifier que la documentation est à jour.
Aujourd’hui toute l’équipe est plus confiante sur notre code et notre documentation. Toutes ces validations ont également aidé les développeurs qui n’étaient pas à l’aise avec l’écriture de la documentation à prendre confiance et être sereins lors de modifications…
Nous avons présenté cet outil lors du Forum PHP 2022 de l’AFUP.
