Documentation d'API avec Swagger/OpenAPI

Toute API a une documentation. La question est seulement de savoir où elle vit et depuis combien de temps elle est fausse. Un fichier Word sur un partage réseau, une page de wiki, une collection Postman exportée par un développeur parti depuis, un fil de discussion où quelqu'un a fini par écrire l'exemple qui marche : ce sont les quatre formes qu'elle prend spontanément, et elles ont toutes le même défaut. Elles sont écrites à côté du code, donc elles divergent du code dès le premier commit qui suit.

Le coût de cette divergence est payé par les autres. Un développeur d'application mobile qui envoie un champ renommé la semaine dernière obtient un 400 qu'il ne comprend pas, écrit un message, attend une réponse, et perd une demi-journée. Multipliez par le nombre de clients et par le rythme des évolutions.

OpenAPI apporte une réponse structurelle plutôt que disciplinaire : la description de l'API est produite depuis le code lui-même. Les chemins viennent des @RequestMapping, les schémas des DTO, les contraintes des annotations de validation. Renommer un champ change la documentation dans le même commit, sans que personne n'ait à y penser. Ce qui reste à écrire à la main, ce sont les intentions — ce que fait un endpoint, pourquoi il peut échouer, ce que le client doit envoyer — c'est-à-dire précisément ce que le code ne peut pas déduire.