← API REST : concevoir, mûrir, documenter

Swagger : éditeur, UI et génération de code

≈ 20 minutes · Jalon M6 · Prérequis : Documenter son API avec OpenAPI

Le gain du jour : transformer le document OpenAPI de la leçon précédente en documentation interactive, en tests exécutables, et en code client généré automatiquement — la dernière marche du cours.

L’écosystème Swagger, en trois outils

Swagger est le nom historique de la suite d’outils (aujourd’hui maintenue par SmartBear) construite autour du format OpenAPI. Trois d’entre eux couvrent l’essentiel des besoins :

Outil	Rôle
Swagger Editor	Éditeur en ligne avec validation en temps réel du document OpenAPI
Swagger UI	Transforme le document en documentation interactive, testable dans le navigateur
Swagger Codegen / OpenAPI Generator	Génère du code client ou serveur à partir du document

Swagger Editor : écrire sans se tromper

Swagger Editor est un éditeur YAML/JSON en ligne, gratuit et open source, qui valide le document OpenAPI au fur et à mesure de la frappe et affiche un aperçu de la documentation générée en direct, côte à côte. C’est l’endroit le plus rapide pour vérifier qu’un document OpenAPI écrit à la main (comme en leçon 9) est syntaxiquement correct avant de l’intégrer à un vrai projet.

Swagger UI : la documentation devient un terrain de jeu

Swagger UI prend le document OpenAPI et génère une page web interactive : chaque endpoint est listé, dépliable, avec ses paramètres, son corps de requête attendu, ses réponses possibles — et surtout, un bouton « Try it out » qui envoie une vraie requête HTTP depuis le navigateur et affiche la vraie réponse du serveur.

# Exemple minimal servi par Swagger UI
openapi: 3.1.0
info:
  title: API Bibliothèque
  version: "1.0.0"
paths:
  /books:
    get:
      summary: Liste les livres
      responses:
        "200":
          description: Liste des livres

Pointer Swagger UI vers ce fichier (ou vers une URL qui le sert) suffit à obtenir une page où n’importe qui — développeur externe, testeur, futur toi dans six mois — peut lire et essayer l’API sans écrire une ligne de code, ni ouvrir Postman.

Le bénéfice concret : la documentation ne peut plus mentir longtemps

Contrairement à un wiki, Swagger UI exécute réellement la requête décrite. Si la documentation dit qu’un champ est optionnel mais que le serveur le refuse, le clic sur « Try it out » le révèle immédiatement — la documentation se vérifie elle-même à chaque utilisation.

Génération de code : ne plus écrire de client à la main

À partir du même document OpenAPI, des générateurs — Swagger Codegen et son successeur communautaire OpenAPI Generator — produisent automatiquement :

un client dans le langage de son choix (Python, TypeScript, Java…), avec une fonction par endpoint, déjà typée selon les schémas ;
parfois un squelette de serveur (les routes et la validation générées, la logique métier à remplir) ;
de la documentation statique (HTML) à héberger sans dépendre d’un serveur Swagger UI vivant.

# Exemple : générer un client TypeScript à partir du document OpenAPI
openapi-generator-cli generate \
  -i openapi.yaml \
  -g typescript-fetch \
  -o ./client

Le vrai gain : un seul document, une seule vérité

Sans génération de code, chaque équipe cliente réécrit sa propre interprétation de l’API — avec ses propres bugs de synchronisation. Avec un document OpenAPI comme source de vérité unique, la documentation interactive (Swagger UI), le client généré, et parfois même des tests de contrat, proviennent tous du même fichier : le mettre à jour met tout le reste à jour.

Où écrire le document OpenAPI : à la main ou généré depuis le code ?

Deux approches coexistent dans l’industrie :

Design-first : on écrit le document OpenAPI avant le code (comme en leçon 9), qui sert de contrat validé avec les équipes clientes avant même que l’implémentation commence.
Code-first : des annotations dans le code du serveur (décorateurs Python avec FastAPI, annotations Java avec springdoc, etc.) génèrent le document OpenAPI automatiquement à partir du code déjà écrit.

Aucune des deux n’est strictement supérieure : design-first force à valider le contrat avant d’investir dans l’implémentation (utile quand plusieurs équipes dépendent de l’API) ; code-first garantit que la documentation ne peut jamais diverger du code réel, au prix d’un contrat moins visible en amont.

Vérifie ta compréhension

1. Que fait concrètement le bouton « Try it out » de Swagger UI ?

2. Quel est l'avantage principal d'utiliser le même document OpenAPI pour la documentation, le client généré et les tests de contrat ?

3. Quelle est la différence entre l'approche « design-first » et « code-first » pour produire un document OpenAPI ?

À toi de jouer

Ouvre Swagger Editor et colle-y le document OpenAPI que tu as écrit dans l’exercice de la leçon précédente (ressource Task). Corrige les erreurs de syntaxe signalées jusqu’à ce que l’aperçu de droite s’affiche proprement.
Dans ce même document, ajoute un exemple (example:) pour chaque champ de ton schéma Task, puis observe comment Swagger UI (aperçu de droite dans l’éditeur) les utilise pour pré-remplir le bouton « Try it out ».

Pour aller plus loin

📖 Sources principales : Swagger Editor, documentation officielle Swagger UI, et OpenAPI Generator — les trois outils couverts dans cette leçon, tous utilisables gratuitement en ligne ou en local.

🗂 Fiche de référence associée : Verbes, codes, en-têtes — antisèche.

C’est la dernière leçon du cours — direction la carte du cours pour une vue d’ensemble, ou l’antisèche pour réviser l’essentiel en un coup d’œil.