Documentation d'API avec OpenAPI/Swagger (`springdoc-openapi-ui`)

Apprenez à générer automatiquement une documentation interactive et standardisée pour vos API REST Spring Boot en utilisant OpenAPI (Swagger) et la bibliothèque springdoc-openapi-ui.

Pourquoi documenter vos API REST est indispensable ?

Une API REST, aussi bien conçue soit-elle, perd une grande partie de sa valeur si elle n'est pas accompagnée d'une documentation claire, précise et à jour. Considérez votre API comme un contrat : elle définit comment les clients doivent interagir avec votre service. Sans documentation, les développeurs consommateurs (frontend, mobile, autres microservices) perdent un temps précieux à essayer de deviner comment utiliser vos endpoints, quels paramètres envoyer, quel format de données est attendu et quelle sera la structure de la réponse.

Une bonne documentation d'API n'est pas un luxe, mais une nécessité. Elle accélère l'intégration des clients, réduit le nombre d'erreurs d'implémentation, facilite la collaboration au sein des équipes et entre les équipes, et rend votre API plus découvrable et plus facile à maintenir. Elle sert de référence unique tant pour les consommateurs que pour les développeurs de l'API elle-même.

Face à ce besoin, une norme s'est imposée pour décrire les API REST de manière standardisée : la spécification OpenAPI (anciennement connue sous le nom de Swagger Specification). OpenAPI définit un format (JSON ou YAML) permettant de décrire la structure complète d'une API : ses endpoints, les opérations disponibles (GET, POST, etc.), les paramètres attendus (chemin, requête, en-tête, corps), les formats de données (schémas), les réponses possibles avec leurs codes de statut, les mécanismes d'authentification, et d'autres métadonnées. L'écosystème Swagger fournit également des outils basés sur cette spécification, notamment la très populaire interface utilisateur Swagger UI.

Intégration transparente avec springdoc-openapi-ui

Pour les développeurs Spring Boot, documenter une API conformément à la spécification OpenAPI est devenu remarquablement simple grâce à la bibliothèque springdoc-openapi-ui. Ce projet communautaire s'intègre parfaitement à Spring Boot et automatise une grande partie du processus de génération de la documentation.

L'intégration commence par l'ajout d'une simple dépendance à votre projet Maven ou Gradle :

Maven (pom.xml) :


    org.springdoc
    springdoc-openapi-starter-webmvc-ui
    2.5.0

Gradle (build.gradle) :

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.5.0' // Vérifiez la dernière version

Une fois cette dépendance ajoutée, la magie opère ! Au démarrage de votre application, springdoc-openapi scanne votre code source, en particulier vos contrôleurs (classes annotées avec @RestController), les annotations de mapping (@GetMapping, @PostMapping, etc.), les paramètres de méthodes (@PathVariable, @RequestParam, @RequestHeader, @RequestBody) et les types de retour (y compris les DTOs). A partir de ces informations, il génère dynamiquement la spécification OpenAPI 3 de votre API.

Par défaut, après avoir ajouté la dépendance et redémarré votre application, deux nouveaux endpoints deviennent disponibles :

/v3/api-docs : Expose la spécification OpenAPI brute au format JSON. D'autres formats (YAML) et des regroupements sont aussi possibles.
/swagger-ui.html : Fournit une interface utilisateur web interactive (Swagger UI) générée à partir de la spécification. Cette interface permet aux utilisateurs de visualiser les endpoints, de lire leur description, de voir les modèles de données (schémas) et même d'essayer directement les appels API depuis leur navigateur.

Aucune configuration supplémentaire n'est requise pour obtenir une documentation de base fonctionnelle et une UI interactive.

Enrichir votre documentation avec les annotations OpenAPI

L'auto-génération est un excellent point de départ, mais pour une documentation véritablement utile, vous voudrez ajouter des descriptions, des exemples et plus de contexte. springdoc-openapi s'intègre avec les annotations standard d'OpenAPI 3 (du package io.swagger.v3.oas.annotations) que vous pouvez placer directement dans votre code de contrôleur et sur vos DTOs.

L'annotation @Operation, placée sur une méthode de contrôleur, permet de décrire l'opération exposée. Ses attributs clés incluent summary (une courte description visible dans la liste des endpoints), description (une explication plus détaillée), tags (pour regrouper les opérations dans l'UI), et responses (pour décrire les réponses possibles).

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
// ...
@Operation(summary = "Récupère un produit par son ID",
           description = "Retourne les détails complets d'un produit spécifique basé sur son identifiant unique.",
           responses = {
               @ApiResponse(responseCode = "200", description = "Produit trouvé et retourné"),
               @ApiResponse(responseCode = "404", description = "Produit non trouvé pour l'ID fourni")
           })
@GetMapping("/{id}")
public ResponseEntity getProductById(@PathVariable Long id) { /* ... */ }

L'annotation @Parameter permet de décrire les paramètres d'une opération (qu'ils proviennent de @PathVariable, @RequestParam, ou @RequestHeader). Vous pouvez spécifier description, required, et example.

import io.swagger.v3.oas.annotations.Parameter;
// ...
@GetMapping("/search")
public List searchProducts(
    @Parameter(description = "Terme de recherche pour le nom du produit", example = "gadget")
    @RequestParam(required = false) String query,
    @Parameter(description = "Nombre maximum de résultats par page", example = "20")
    @RequestParam(defaultValue = "10") int size) { /* ... */ }

L'annotation @ApiResponse (souvent utilisée dans @Operation) décrit une réponse HTTP spécifique. L'attribut responseCode indique le code de statut (ex: "200", "404"), description explique la signification de cette réponse, et content peut lier la réponse à un schéma de données (@Schema).

L'annotation @Schema est cruciale pour décrire les modèles de données (vos DTOs). Placée sur une classe DTO, elle peut fournir une description générale. Placée sur les champs du DTO, elle permet de décrire chaque propriété avec description, example, requiredMode (REQUIRED ou NOT_REQUIRED), etc.

import io.swagger.v3.oas.annotations.media.Schema;

@Schema(description = "Représentation d'un produit dans l'API")
public class ProductDto {

    @Schema(description = "Identifiant unique du produit", example = "123", accessMode = Schema.AccessMode.READ_ONLY)
    private Long id;

    @Schema(description = "Nom du produit", example = "Super Widget", requiredMode = Schema.RequiredMode.REQUIRED)
    private String name;

    @Schema(description = "Prix du produit", example = "49.99")
    private Double price;
    // ... Getters / Setters ...
}

Enfin, l'annotation @Tag, généralement placée au niveau de la classe du contrôleur, permet de regrouper logiquement les endpoints dans Swagger UI. Vous pouvez fournir un name et une description pour chaque tag.

import io.swagger.v3.oas.annotations.tags.Tag;

@RestController
@RequestMapping("/api/products")
@Tag(name = "Gestion des Produits", description = "API pour les opérations CRUD sur les produits")
public class ProductController { /* ... */ }

Configuration globale et points d'attention

Au-delà des annotations, vous pouvez configurer des informations globales sur votre API (titre, version, description générale, informations de contact, licence) via des propriétés dans votre fichier application.properties ou application.yml. Utilisez les propriétés préfixées par springdoc.api-docs.* et springdoc.info.*.

Exemple (application.yml) :

springdoc:
  api-docs:
    path: /mon-api/v3/api-docs # Changer le chemin par défaut
  info:
    title: Mon API de Produits Incroyables
    version: 1.2.3
    description: Une API pour gérer des produits absolument essentiels.
    contact:
      name: Support CertiQuizz
      email: support@certiquizz.com
      url: https://certiquizz.com/support
    license:
      name: Apache 2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html
  swagger-ui:
    path: /mon-api/swagger-ui.html # Changer le chemin par défaut de Swagger UI
    display-request-duration: true
    operations-sorter: alpha
    tags-sorter: alpha
# Configuration des serveurs (optionnel)
# servers:
#  - url: https://prod.certiquizz.com/api
#    description: Serveur de Production
#  - url: https://staging.certiquizz.com/api
#    description: Serveur de Staging

Il est également possible de définir les serveurs cibles (URL de base de votre API dans différents environnements) via la configuration ou des annotations @OpenAPIDefinition, ce qui est utile pour la documentation générée.

Un point crucial concerne la sécurité. En production, vous ne voulez probablement pas exposer publiquement votre documentation d'API interactive, surtout si elle permet d'exécuter des requêtes. Assurez-vous de sécuriser les endpoints /swagger-ui.html et /v3/api-docs (et leurs équivalents configurés) à l'aide de Spring Security, en les rendant accessibles uniquement aux utilisateurs authentifiés et autorisés (par exemple, les administrateurs ou les développeurs internes).

En résumé, springdoc-openapi-ui offre une solution puissante et élégante pour générer et maintenir une documentation d'API REST de haute qualité pour vos applications Spring Boot. En combinant l'auto-génération avec une utilisation judicieuse des annotations OpenAPI, vous fournissez un outil indispensable à tous les consommateurs de votre API, facilitant leur travail et améliorant la qualité globale de votre écosystème applicatif.

◄ Précédent Suivant ►

く