OpenAPI / Swagger Java : méthodes, exemples, installation…

Qu'est-ce qu'OpenAPI / Swagger et pourquoi l'utiliser en Java ?

OpenAPI (anciennement Swagger) est une spécification permettant de décrire, créer, documenter et consommer des API RESTful. Pour un développeur Java, les bibliothèques OpenAPI / Swagger sont des outils indispensables qui automatisent la documentation des API et la génération de code client.

Les principales raisons d'utiliser OpenAPI / Swagger dans vos projets Java :

Génération automatique de documentation — la bibliothèque analyse votre code (annotations Spring Boot, JAX-RS) et crée une documentation interactive au format Swagger UI.
Standardisation — un format unique de description d'API, compréhensible aussi bien par les humains que par les machines.
Génération de code client — vous pouvez générer un client Java pour toute API décrite en OpenAPI.
Tests — Swagger UI permet d'effectuer des requêtes vers l'API directement depuis le navigateur.
Intégration CI/CD — vous pouvez vérifier la conformité de l'API à la spécification dès l'étape de build.

Dans cet article, nous allons explorer les deux principales bibliothèques Java : springdoc-openapi (pour Spring Boot) et Swagger Core (pour JAX-RS et autres frameworks).

Installation de la bibliothèque OpenAPI / Swagger pour Java

L'installation dépend du framework utilisé. Voici les deux options principales.

Option 1 : Spring Boot (springdoc-openapi)

Ajoutez la dépendance dans votre fichier pom.xml (Maven) :

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

Pour Gradle (build.gradle) :

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

Option 2 : JAX-RS / Jakarta (Swagger Core)

Maven :

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2-jakarta</artifactId>
    <version>2.2.22</version>
</dependency>

Gradle :

implementation 'io.swagger.core.v3:swagger-jaxrs2-jakarta:2.2.22'

Démarrage rapide : premier exemple avec Spring Boot

Après avoir ajouté la dépendance springdoc-openapi à votre projet Spring Boot, Swagger UI est automatiquement accessible à l'adresse http://localhost:8080/swagger-ui.html. Créons un contrôleur simple :

import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.springframework.web.bind.annotation.*;

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

    @GetMapping("/{id}")
    @Operation(summary = "Récupérer un utilisateur par son ID")
    public String getUser(@PathVariable Long id) {
        return "Utilisateur avec ID : " + id;
    }

    @PostMapping
    @Operation(summary = "Créer un nouvel utilisateur")
    public String createUser(@RequestBody String userName) {
        return "Utilisateur créé : " + userName;
    }
}

Après avoir lancé l'application, ouvrez http://localhost:8080/swagger-ui.html — vous verrez une documentation interactive vous permettant d'exécuter des requêtes.