Documentation des API avec Postman et OpenAPI

1. Documenter avec une Collection Postman

Vous avez déjà utilisé Postman pour tester manuellement vos endpoints. Mais c'est aussi un excellent outil pour créer une documentation vivante. L'idée est de créer une "collection" de requêtes pré-configurées qui non seulement montre comment utiliser l'API, mais permet aussi de l'exécuter directement.

Une collection Postman bien organisée est une forme de documentation très appréciée car elle est immédiatement exploitable.

Création et Organisation d'une Collection

La vidéo ci-dessous est un guide complet pour démarrer avec Postman. Elle vous montrera comment structurer votre travail pour documenter une API.

Documenter chaque requête

Une fois la structure en place, chaque requête doit être un exemple clair d'utilisation. Pour cela, Postman permet d'ajouter des descriptions détaillées.

Pour chaque requête de votre API (ex: POST /api/products), vous devriez :

1. Donner un nom explicite : "Créer un nouveau produit".
2. Ajouter une description : Cliquez sur l'icône de documentation (ressemble à une page) à droite du nom de la requête. Vous pouvez y décrire le but de l'endpoint, les paramètres attendus, et le format du corps de la requête.
3. Fournir un exemple de corps de requête (Body) : Pour les requêtes POST ou PUT, remplissez le corps avec un exemple de JSON valide.
4. Enregistrer des exemples de réponses : Après avoir exécuté une requête avec succès, vous pouvez sauvegarder la réponse comme un exemple. C'est très utile pour montrer à quoi ressemblent les réponses 200 (OK), 201 (Created), 404 (Not Found), etc.

La vidéo précédente montre également comment configurer et exécuter les différents types de requêtes. Inspirez-vous-en pour documenter les endpoints CRUD de votre projet.

Une fois votre collection complète, vous pouvez l'exporter en un fichier JSON et la partager avec votre équipe, ou même générer une documentation web publique via Postman.

2. Documentation avec OpenAPI et Swagger UI

La documentation avec Postman est pratique, mais elle peut devenir désynchronisée avec le code si vous oubliez de la mettre à jour. L'approche la plus robuste et professionnelle consiste à générer la documentation directement depuis le code source. C'est le principe d'OpenAPI.

• OpenAPI : C'est une spécification (un standard) pour décrire des API REST. Le résultat est un fichier JSON ou YAML qui détaille tous les endpoints, paramètres, modèles de données et réponses.
• Swagger UI : C'est un outil qui prend ce fichier OpenAPI et génère une interface web interactive, esthétique et très pratique.

Intégration dans Spring Boot avec springdoc-openapi

Pour intégrer cela à notre projet, nous allons utiliser la bibliothèque springdoc-openapi. Elle analyse notre code Spring (contrôleurs, annotations @GetMapping, DTOs, etc.) et génère automatiquement la spécification OpenAPI.

Étape 1 : Ajouter la dépendance Maven

Ouvrez votre pom.xml et ajoutez cette dépendance :

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.5.0</version> <!-- Utilisez la dernière version compatible -->
</dependency>

Étape 2 : C'est (presque) tout !

Redémarrez votre application. springdoc expose automatiquement deux nouveaux endpoints :

• http://localhost:8080/v3/api-docs : Le fichier de spécification OpenAPI brut au format JSON.
• http://localhost:8080/swagger-ui.html : L'interface web interactive Swagger UI.

Allez sur swagger-ui.html dans votre navigateur. Vous devriez déjà voir une documentation basique de votre API !

Enrichir la Documentation avec des Annotations

La documentation auto-générée est un bon début, mais elle manque de détails. Nous allons l'enrichir avec des annotations directement dans notre code de contrôleur.

L'article suivant est une référence excellente et concise pour comprendre comment utiliser les annotations OpenAPI avec springdoc.

Mise en pratique : Documentons notre ProductController

Voici à quoi pourrait ressembler une méthode de votre ProductController une fois documentée.

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.media.Content;
import io.swagger.v3.oas.annotations.media.Schema;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/products")
@Tag(name = "Gestion des Produits", description = "API pour les opérations CRUD sur les produits") // Regroupe les endpoints sous ce nom
public class ProductController {

    // ... Injection du service ...

    @GetMapping("/{id}")
    @Operation(summary = "Récupérer un produit par son ID", description = "Retourne un seul produit basé sur son identifiant unique.")
    @ApiResponses(value = {
            @ApiResponse(responseCode = "200", description = "Produit trouvé",
                    content = { @Content(mediaType = "application/json",
                            schema = @Schema(implementation = ProductDTO.class)) }),
            @ApiResponse(responseCode = "404", description = "Produit non trouvé",
                    content = @Content)
    })
    public ResponseEntity<ProductDTO> getProductById(@PathVariable Long id) {
        // ... votre logique ...
    }

    // ... autres méthodes ...
}

Décortiquons les annotations :

• @Tag(name = "..."): Donne un nom convivial au groupe d'endpoints de ce contrôleur dans l'UI Swagger.
• @Operation(summary = "..."): Fournit un résumé court et clair de ce que fait la méthode.
• @ApiResponses: Un conteneur pour plusieurs réponses possibles.
• @ApiResponse(responseCode = "200", ...): Décrit une réponse spécifique. Ici, une réponse 200 OK avec un corps JSON correspondant à notre ProductDTO.
• @ApiResponse(responseCode = "404", ...): Décrit le cas d'erreur où le produit n'est pas trouvé.

En ajoutant ces annotations à travers vos contrôleurs, votre documentation deviendra une référence complète et fiable pour quiconque souhaite utiliser votre API.

Postman vs. Swagger : Lequel choisir ?

Vous vous demandez peut-être quelle approche privilégier. La réponse est simple : les deux sont utiles et complémentaires.

• Swagger/OpenAPI est idéal comme source de vérité unique. Comme la documentation est générée à partir du code, elle est toujours à jour. C'est la référence formelle de votre API.
• Postman est excellent pour la documentation interactive et le test collaboratif. De nombreux outils permettent d'importer une spécification OpenAPI pour générer automatiquement une collection Postman ! Vous bénéficiez ainsi du meilleur des deux mondes : une documentation formelle et une collection de tests toujours synchronisée.

En tant que développeur backend, maîtriser springdoc est une compétence clé. En tant que potentiel QA Engineer, savoir créer et maintenir des collections Postman est tout aussi fondamental.

Conclusion

Félicitations ! Vous avez non seulement construit une API REST complète et sécurisée, mais vous savez maintenant comment la documenter de manière professionnelle. C'est une compétence qui distingue un développeur amateur d'un professionnel.

Points clés à retenir :

• Une bonne documentation est essentielle pour l'adoption et la maintenance d'une API.
• Postman permet de créer des collections de requêtes qui servent de documentation interactive et pratique.
• OpenAPI est un standard pour décrire les API REST, et Swagger UI en fournit une représentation visuelle et interactive.
• La bibliothèque springdoc-openapi automatise la génération de la documentation OpenAPI pour les applications Spring Boot.
• Les annotations comme @Tag, @Operation, et @ApiResponse sont utilisées pour enrichir le code et produire une documentation détaillée et précise.

Cette leçon marque la fin de notre projet de synthèse et de ce cours. Vous avez parcouru un chemin impressionnant, depuis les bases de Java jusqu'à la construction d'une API REST de niveau professionnel avec Spring Boot, incluant la gestion de données, la sécurité, les tests et la documentation. Vous disposez maintenant de toutes les bases nécessaires pour aborder des projets backend Java avec confiance. Bravo pour votre travail et votre persévérance