Chaque API a une documentation que personne ne lit de bout en bout. Une spécification OpenAPI peut compter des centaines de lignes décrivant des chemins, des méthodes, la forme des requêtes et des réponses, et les ressources qu'elles manipulent. Elle est précise et complète, et presque impossible à garder en tête. Ce que vous voulez vraiment, en arrivant sur un nouveau service, c'est une image : quelles sont les ressources principales, quels endpoints les touchent, et comment tout cela s'articule-t-il ?
Cette image est déjà latente dans la spécification. Un document OpenAPI ou équivalent est une donnée structurée, ce qui signifie qu'un outil peut le lire et dessiner la forme que vous devriez sinon reconstituer à la main.
Ce que la spécification OpenAPI vous dit déjà
Un document d'API bien formé contient plus de structure qu'il n'y paraît. Vous pouvez en déduire :
- Les ressources, à partir des schémas et des segments de chemin (users, orders, products).
- Les opérations, à partir des méthodes de chaque chemin (lister, créer, mettre à jour, supprimer).
- Les relations, à partir des références entre schémas (un Order référence un User et des Line Items).
- Le regroupement, à partir des tags, qui correspondent généralement aux vrais modules du service.
Lire tout cela sous forme de texte est lent. Le voir sous forme de diagramme est instantané, et c'est dans le diagramme que survient le moment « ah, c'est comme ça que tout s'emboîte ».
Le déroulé
C'est vraiment coller et c'est parti. Donnez votre document OpenAPI à l'outil : il en extrait les ressources et les relations et les dispose sous forme de formes modifiables. Ensuite, vous faites la mise en forme habituelle : regrouper par tag, mettre en évidence la ressource centrale, masquer les endpoints qui ne sont que du bruit pour ce diagramme précis.
La spécification est la source de vérité de l'API. Générer le diagramme à partir d'elle signifie que l'image et le contrat ne peuvent pas se contredire.
Pourquoi le dériver plutôt que le dessiner
Vous pourriez dessiner un diagramme d'API à la main, et il serait faux dès que quelqu'un ajouterait un endpoint. Le dériver de la spécification lie l'image au contrat. Quand l'API change, vous régénérez, et le diagramme est de nouveau à jour en quelques secondes. Pour un service qui évolue, c'est la différence entre une documentation à laquelle on fait confiance et une documentation qu'on ignore discrètement.
Au-delà d'un seul service
La même idée passe à l'échelle. Si vous avez plusieurs services, chacun avec sa propre spécification, vous pouvez construire une carte de plus haut niveau : quel service possède quelles ressources, et où l'un appelle l'autre. C'est le diagramme que personne n'a jamais le temps de tenir à jour à la main, et précisément celui qui fait gagner un après-midi pendant un incident. Laissez les spécifications le dessiner, puis façonnez-le pour obtenir la vue dont votre équipe a besoin.
Arrêtez de lire du YAML pour comprendre un service. Collez la spécification et lisez plutôt l'image.