Tutoriel documentation API Swagger pour débutants - 1 - Introduction à la documentation API avec Swagger

Qu’est-ce que Swagger ?

Swagger™ vise à définir une interface standard, indépendante du langage, pour les APIs REST. Cela permet aux humains et aux machines de découvrir et de comprendre les fonctionnalités d’un service sans avoir accès au code source, à la documentation ou en inspectant le trafic réseau. Lorsqu’une API est correctement définie via Swagger, un utilisateur peut la comprendre et l’utiliser avec un minimum de logique d’implémentation. À l’image des interfaces en programmation bas niveau, Swagger élimine les devinettes pour appeler un service.

Techniquement parlant, Swagger est une spécification formelle entourée d’un écosystème complet d’outils, allant des interfaces utilisateur front-end, aux bibliothèques de code bas niveau et aux solutions commerciales de gestion d’API.

Par où commencer ?

Si vous êtes un fournisseur d’API et souhaitez utiliser Swagger pour décrire vos APIs, plusieurs approches sont possibles :

Une approche descendante (*top-down*) où vous utilisez l’éditeur Swagger pour créer votre définition Swagger, puis utilisez les outils intégrés Swagger Codegen pour générer l’implémentation côté serveur.
Si o