CarmaBlog

 English version available

A l’heure où les projets informatiques se basent la plupart du temps sur une architecture orientée microservices, il n’est pas étonnant que les différents microservices soient développés et maintenus par des équipes différentes.

Chaque service fournit une API (privée ou public) qui permet de communiquer avec le monde extérieur tout en garantissant l’intégrité de ses données. De multiples appels imbriqués entre les microservices permettent de réaliser un traitement plus complexe. Il est très important d’avoir une documentation à jour pour chacune de vos API. Qui n’a jamais entendu un développeur dire à un autre « Cette doc n’a pas été mise à jour depuis des mois, regarde le code directement! ».

Swagger UI se conforme à cette affirmation. Il suffit d’ajouter des annotations précises dans votre code et le framework s’occupera de générer de manière semi-automatique toute la documentation de votre API. ‘Semi-automatique’ car il ne peut pas écrire la documentation métier, vous devez donc l’écrire vous-même, un peu comme si vous écrivez de la Javadoc.

La documentation générée par Swagger est donc mise à jour en même temps que le code. Par exemple, si vous ajoutez un nouveau paramètre à une méthode exposée, celui-ci sera automatiquement pris en compte et documenté avec les annotations adéquates. La documentation n’est pas seulement un fichier HTML statique, elle permet de faire office de client HTTP (il n’y a pas besoin d’avoir Postman installé par exemple) pour tester les différentes méthodes exposées par l’API.

Vous pouvez regarder l’application exemple officielle (Petstore) pour avoir un accès aux différentes fonctionnalités supportées, par exemple l’authentification OAuth2.0 est supportée.

Exemple d'application avec Swagger

Cerise sur le gâteau si vous utilisez Spring MVC dans votre application, le projet SpringFox (surcouche Swagger) rend l’intégration de Swagger très simple. En moins d’une heure, vous devriez être capable de générer la documentation de votre API. Ensuite, vous pourrez ajouter des annotations optionnelles pour la rendre plus complète.

En adoptant Swagger sur l’ensemble de vos microservices, il est fort à parier que la communication entre vos différentes équipes s’améliore. Désormais, vous n’aurez qu’un seul point d’entrée, oubliez donc la page wiki mal-documentée qui avait tendance à prendre la poussière… En vous souhaitant une bonne documentation!