Génération Swagger/OpenAPI pour Java : meilleures bibliothèques

Génération Swagger/OpenAPI pour Java : guide complet des outils

Dans le développement Java moderne, la création d'une documentation API de qualité est devenue une partie intégrante du processus. La spécification OpenAPI (anciennement connue sous le nom de Swagger) fournit un format standardisé pour décrire les API RESTful. Dans cet article, nous examinerons les principaux outils de génération de documentation Swagger/OpenAPI dans les projets Java, leurs caractéristiques et des exemples d'utilisation.

Qu'est-ce que Swagger et OpenAPI ?

Swagger est un ensemble d'outils pour concevoir, créer et documenter les API REST. OpenAPI est une spécification qui définit la norme de description des API. Swagger est l'implémentation la plus populaire de cette spécification.

Bibliothèques principales pour Java

Examinons trois outils clés :

• SpringDoc OpenAPI — une bibliothèque moderne pour Spring Boot
• Swagger Core — la bibliothèque de base des créateurs de Swagger
• OpenAPI Generator — un outil pour générer du code et de la documentation

1. SpringDoc OpenAPI

SpringDoc est le choix le plus populaire pour les projets Spring Boot. Il s'intègre automatiquement à votre application et génère la documentation à partir des annotations et des types de données.

Installation et configuration

Ajoutez la dépendance dans pom.xml :

<dependency>    <groupId>org.springdoc</groupId>    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>    <version>2.6.0</version></dependency>

Exemple d'utilisation

Créez un contrôleur simple avec documentation :

@RestController@RequestMapping("/api/users")@Tag(name = "Utilisateurs", description = "Gestion des utilisateurs")public class UserController {

    @GetMapping("/{id}")    @Operation(summary = "Obtenir un utilisateur par ID")    public ResponseEntity<User> getUser(            @Parameter(description = "ID de l'utilisateur")            @PathVariable Long id) {        // implémentation        return ResponseEntity.ok(new User(id, "Ivan"));    }

    @PostMapping    @Operation(summary = "Créer un nouvel utilisateur")    public ResponseEntity<User> createUser(            @RequestBody @Valid CreateUserRequest request) {        // implémentation        return ResponseEntity.status(201).body(new User(1L, request.getName()));    }}

Après le démarrage de l'application, la documentation sera accessible à l'adresse http://localhost:8080/swagger-ui.html.

2. Swagger Core

La bibliothèque Swagger Core offre une approche de plus bas niveau pour créer la spécification OpenAPI. Elle convient aux projets où un contrôle total sur la génération est requis.

Exemple de création manuelle de spécification

import io.swagger.v3.oas.models.*;import io.swagger.v3.oas.models.info.*;

OpenAPI openAPI = new OpenAPI()    .info(new Info()        .title("API Pet Store")        .description("API pour la gestion des animaux de compagnie")        .version("1.0.0")        .contact(new Contact()            .name("Développeur")            .email("dev@example.com")))    .addServersItem(new Server()        .url("https://api.example.com/v1")        .description("Serveur de production"));

// Ajout des chemins et composantsPaths paths = new Paths();paths.addPathItem("/pets", new PathItem()    .get(new Operation()        .operationId("listPets")        .summary("Obtenir la liste des animaux de compagnie")));openAPI.setPaths(paths);

3. OpenAPI Generator

OpenAPI Generator est un outil qui peut générer à la fois de la documentation et du code client/serveur à partir de la spécification OpenAPI.

Utilisation avec Maven

Ajoutez le plugin dans pom.