Bonjour ! Dans notre dernière leçon, nous avons rendu notre API REST extrêmement flexible en y ajoutant des fonctionnalités de tri, de pagination et de recherche avancée. Une API puissante est une excellente chose, mais son utilité est limitée si personne ne sait comment l'utiliser. Comment un développeur frontend peut-il connaître tous les endpoints disponibles, les paramètres de requête attendus et la structure des réponses ?
C'est précisément le problème que nous allons résoudre aujourd'hui. L'objectif de cette leçon est d'apprendre à documenter automatiquement une API avec OpenAPI (Swagger). Nous allons transformer notre code source en une documentation interactive, vivante et toujours à jour, qui servira de contrat et de guide pour tous les consommateurs de notre API. C'est une pratique standard et essentielle dans le développement professionnel.
Qu'est-ce que OpenAPI et Swagger ?
Avant de commencer, il est important de clarifier deux termes que vous entendrez souvent :
- OpenAPI est une spécification (une norme). C'est un format standard, indépendant du langage, pour décrire des APIs REST. On peut le voir comme un "blueprint" de votre API, généralement écrit en JSON ou YAML.
- Swagger est un ensemble d'outils qui implémentent la spécification OpenAPI. L'outil le plus connu est Swagger UI, qui prend une spécification OpenAPI et génère une belle interface web interactive pour visualiser et tester l'API.
Dans cette leçon, nous utiliserons la bibliothèque springdoc-openapi, qui inspecte nos contrôleurs Spring Boot et génère automatiquement la spécification OpenAPI, que nous pourrons ensuite visualiser avec Swagger UI.
Swagger UI Integration in Spring Boot 3 (Beginner-Friendly)
Pour bien comprendre la distinction, regardez cette courte introduction de la vidéo "Swagger UI Integration in Spring Boot 3" par CyberJAR. Elle clarifie parfaitement le rôle de chacun.
Regardez le début de la vidéo, de 00:33 à 02:24. Concentrez-vous sur la définition claire de OpenAPI comme la "spécification" et de Swagger comme le "toolkit" qui l'utilise.
1. Mise en Place : Une Dépendance pour les Gouverner Toutes
L'intégration de la documentation OpenAPI dans un projet Spring Boot 3 est remarquablement simple. Il suffit d'ajouter une seule dépendance à votre fichier pom.xml.
La vidéo suivante vous montrera la dépendance exacte à utiliser et ce que vous obtenez "gratuitement" juste en l'ajoutant.
Spring boot 3 - OpenApi Documentation | Swagger UI
La vidéo "Spring boot 3 - OpenApi Documentation | Swagger UI" par Ali Bouali est un guide pratique très complet que nous suivrons tout au long de cette leçon. Commençons par la mise en place.
Regardez la vidéo de 02:56 à 04:39. L'auteur explique quelle version de la bibliothèque utiliser pour Spring Boot 3 (c'est important !) et montre comment ajouter la dépendance springdoc-openapi-starter-webmvc-ui dans le pom.xml.
Une fois cette dépendance ajoutée et votre application redémarrée, deux nouveaux endpoints sont disponibles :
http://localhost:8080/v3/api-docs: Cet endpoint retourne la spécification OpenAPI brute au format JSON.http://localhost:8080/swagger-ui/index.html: C'est ici que la magie opère. Vous y trouverez l'interface Swagger UI générée à partir de la spécification.
2. Gérer Spring Security : Le Piège du 403 Forbidden
Si vous essayez d'accéder à l'URL de Swagger UI maintenant, vous allez très probablement rencontrer une erreur HTTP 403 Forbidden. C'est normal ! Notre application est protégée par Spring Security, qui, par défaut, bloque tout ce qui n'est pas explicitement autorisé.
Nous devons configurer notre SecurityFilterChain pour autoriser l'accès aux URLs nécessaires à Swagger UI.
Spring boot 3 - OpenApi Documentation | Swagger UI
Continuons avec la vidéo d'Ali Bouali. Cette section aborde un problème très courant et montre comment le résoudre.
Regardez attentivement de 04:50 à 08:15. Observez comment il modifie la configuration de sécurité (SecurityConfig) en ajoutant une liste de chemins (/v3/api-docs/**, /swagger-ui/**, etc.) à la méthode requestMatchers(...).permitAll().
C'est une étape cruciale. En autorisant ces chemins, vous permettez à Swagger UI de charger ses ressources et de communiquer avec l'endpoint /v3/api-docs pour construire la documentation.
3. Enrichir la Documentation avec les Annotations
Maintenant que l'interface est accessible, il est temps de la rendre vraiment utile. La documentation de base est bien, mais elle manque de contexte. Nous allons utiliser des annotations directement dans notre code de contrôleur pour l'enrichir.
Voici les annotations les plus importantes :
@Tag(name = "..."): Placée sur une classe de contrôleur, elle permet de nommer et de regrouper les endpoints dans l'interface UI.@Operation(summary = "...", description = "..."): Placée sur une méthode d'endpoint, elle fournit un titre court (summary) et une description plus détaillée de ce que fait l'opération.@ApiResponse(responseCode = "...", description = "..."): Permet de décrire les réponses possibles d'un endpoint (ex:200 OK,404 Not Found,400 Bad Request). On peut en utiliser plusieurs, regroupées dans@ApiResponses.
Votre expérience avec les frameworks web comme Laravel vous a habitué à une organisation claire des routes et des contrôleurs; ces annotations remplissent un rôle similaire pour la documentation.
Spring boot 3 - OpenApi Documentation | Swagger UI
La vidéo suivante montre comment utiliser ces annotations pour transformer une documentation basique en un guide clair et détaillé.
Regardez de 27:27 à 32:16. Concentrez-vous sur l'ajout des annotations @Tag, @Operation et @ApiResponse à un contrôleur et à ses méthodes. Voyez l'impact direct de ces changements sur l'interface Swagger UI après le redémarrage de l'application.
4. Configuration Globale et Gestion de l'Authentification JWT
Pour une documentation vraiment professionnelle, nous devons configurer deux derniers éléments : des informations générales sur l'API et la manière de gérer notre authentification par token JWT.
A. Informations Générales de l'API
Nous pouvons définir un titre, une description, une version, des informations de contact, etc. pour notre API. Cela se fait de manière très propre en créant une classe de configuration et en utilisant des annotations.
B. Intégration de l'Authentification JWT
C'est une étape fondamentale. Pour que les développeurs puissent tester les endpoints sécurisés directement depuis Swagger UI, nous devons lui indiquer que notre API utilise une authentification de type "Bearer Token" et lui fournir un moyen d'entrer un token JWT.
Cela se fait en deux temps :
- Définir un
SecurityScheme: On décrit notre mécanisme de sécurité (JWT Bearer). - Appliquer ce
SecurityRequirement: On indique quels endpoints (ou tous) nécessitent cette sécurité.
Le résultat sera l'apparition d'un bouton "Authorize" dans l'interface, qui permettra de "s'authentifier" auprès de Swagger UI.
Spring boot 3 - OpenApi Documentation | Swagger UI
Les prochaines sections de la vidéo d'Ali Bouali couvrent parfaitement ces deux aspects.
Regardez les sections suivantes : Informations Globales (12:22 - 18:47) : Observez la création d'une classe OpenAPIConfig et l'utilisation de @OpenAPIDefinition et @Info pour ajouter des métadonnées (titre, version, contact, serveurs). Définir le Schéma de Sécurité (19:04 - 21:37) : Voyez comment l'annotation @SecurityScheme est utilisée pour définir l'authentification BearerAuth de type HTTP avec le format JWT. Appliquer la Sécurité (23:17 - 27:27) : Comprenez comment l'attribut security de @OpenAPIDefinition est utilisé pour appliquer ce schéma de sécurité à tous les endpoints de l'API, faisant apparaître le cadenas à côté de chaque opération.
Astuce : Masquer des Endpoints
Parfois, certains endpoints sont à usage interne ou ne sont pas destinés à être exposés dans la documentation publique. L'annotation @Hidden peut être placée sur une méthode ou même sur une classe de contrôleur entière pour la masquer de Swagger UI. C'est simple et efficace. La vidéo en fait une démonstration rapide de 32:16 à 34:19 (section 7).
Conclusion
Félicitations ! Vous savez maintenant comment produire une documentation d'API professionnelle, interactive et toujours synchronisée avec votre code. C'est une compétence extrêmement précieuse qui facilite la collaboration entre les équipes backend, frontend et QA.
Points clés à retenir :
- Intégration facile : La bibliothèque
springdoc-openapi-starter-webmvc-uifait presque tout le travail. - La sécurité d'abord : N'oubliez pas de configurer Spring Security pour autoriser l'accès aux endpoints de Swagger UI.
- Les annotations sont clés :
@Tag,@Operation,@ApiResponseenrichissent votre documentation et la rendent compréhensible. - Gestion de l'authentification : La configuration d'un
@SecuritySchemepour JWT est indispensable pour permettre de tester les endpoints sécurisés directement depuis l'interface. - Documentation vivante : Le plus grand avantage est que la documentation est générée à partir du code. Quand le code change, la documentation change. Fini les documentations obsolètes !
Maintenant que notre API backend est complète, fonctionnelle et parfaitement documentée, il reste une dernière étape avant de pouvoir la connecter à un frontend React : gérer les politiques de sécurité des navigateurs.
Dans notre prochaine leçon, nous aborderons le CORS (Cross-Origin Resource Sharing). Nous apprendrons à configurer notre application Spring Boot pour qu'elle accepte en toute sécurité les requêtes provenant de notre application frontend, qui sera hébergée sur une origine (domaine) différente.