Baklava transforme les tests d'API Scala en documentation vivante
La documentation des API est toujours en retard sur le code... jusqu'à présent. Baklava, une bibliothèque open source pour Scala, inverse la tendance en faisant des tests de routage la source unique de vérité, à la fois pour le comportement et la documentation. Lorsque les tests réussissent, la bibliothèque produit du HTML lisible par les humains, une spécification OpenAPI lisible par les machines et des clients TypeScript prêts à l'emploi. Le décalage de la documentation devient structurellement impossible, car les docs ne sont générées que lorsque les tests passent.
Des tests qui font office de documentation
Baklava s'intègre directement aux suites de tests existantes pour Pekko HTTP et http4s. Au lieu d'écrire des assertions, les développeurs définissent des routes avec des blocs path(), supports() et onRequest() qui vérifient à la fois le comportement de l'API et le décrivent pour la sortie de documentation. Un test échoué bloque la génération de la documentation, garantissant que le contrat publié correspond toujours au service en cours d'exécution. Cette approche élimine la surcharge manuelle de synchronisation des spécifications.
Sept formats, un seul flux
Chaque sortie supportée—HTML simple, OpenAPI 3.0.1, paquets TypeScript, collections Postman et clients Scala sttp—est générée automatiquement via SBT. La bibliothèque prend en charge Scala 2.13 et 3, JDK 11+, et s'intègre à ScalaTest, Specs2 et MUnit. Comme chaque format est une dépendance SBT indépendante découverte à l'exécution, les équipes peuvent adopter uniquement ce dont elles ont besoin sans réécrire leurs outils.
Un changement culturel pour les équipes API
Pourquoi c'est important
Baklava s'attaque à la cause racine des documentations d'API peu fiables—la maintenance parallèle—en faisant de la suite de tests le contrat autoritaire. Les équipes qui l'adoptent réduisent le risque d'échecs en production dus à des spécifications obsolètes et diminuent la charge cognitive liée à la synchronisation de multiples artefacts. Dans les environnements où les contrats d'API guident le développement en aval, cette bibliothèque transforme la documentation, passant d'une responsabilité à un sous-produit de l'excellence technique.
Source : DEV Community. Synthèse éditoriale assistée par IA — TechnoExpress.