Accueil › Spring Boot › Documenter son API avec OpenAPI (springdoc)
Documenter son API avec OpenAPI (springdoc)
Appeler et documenter des APIintermediaire
OpenAPI est une spécification qui décrit une API REST (endpoints, paramètres, schémas, codes de réponse) dans un format standard. springdoc-openapi génère cette description automatiquement à partir des @RestController d'une application Spring Boot, sans écrire de fichier YAML à la main.
Ajouter la dépendance :
<dependency>
<groupId>org.springdoc</groupId>
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
<version>2.x.x</version>
</dependency>
Au démarrage, deux URL sont disponibles sans rien configurer de plus :
/v3/api-docs: la description OpenAPI en JSON./swagger-ui.html: une interface web pour explorer et tester l'API.
springdoc déduit déjà beaucoup de choses du code : les chemins, les méthodes HTTP, les types de paramètres, et même les contraintes Bean Validation (@NotBlank, @Min…) présentes sur les DTO. Pour aller plus loin, on ajoute des annotations dédiées :
@Tag(name = "Produits")
@RestController
@RequestMapping("/produits")
public class ProduitController {
@Operation(summary = "Récupère un produit par son identifiant")
@ApiResponse(responseCode = "404", description = "Produit introuvable")
@GetMapping("/{id}")
public Produit trouver(@PathVariable Long id) { ... }
}
En production, on désactive généralement Swagger UI et l'endpoint de description (springdoc.swagger-ui.enabled=false, springdoc.api-docs.enabled=false), pour ne pas exposer la structure de l'API publiquement.
Les termes à connaître
- OpenAPI
Spécification standard (au format JSON ou YAML) qui décrit une API REST : ses endpoints, leurs paramètres, les schémas des corps de requête et de réponse, les codes de statut possibles. Elle sert de contrat lisible par des humains et par des outils (génération de clients, tests, portails de documentation).
- springdoc-openapi-starter-webmvc-ui
Dépendance à ajouter au projet pour générer automatiquement la documentation OpenAPI d'une application Spring MVC, en inspectant les
@RestControllerau démarrage, et pour exposer l'interface Swagger UI.- /v3/api-docs
URL exposée par springdoc où l'on récupère la description OpenAPI générée, au format JSON (ajouter
.yamlpour la variante YAML :/v3/api-docs.yaml).- Swagger UI
Interface web interactive, servie par défaut sur
/swagger-ui.html(qui redirige vers/swagger-ui/index.html), qui affiche la documentation générée et permet de tester les endpoints directement depuis le navigateur.- @Operation / @Tag
@Operationdocumente un endpoint (résumé, description) au-delà de ce que Spring peut déduire seul.@Tag, posée sur le contrôleur, regroupe ses endpoints sous un même nom dans Swagger UI.- @Schema
Documente un champ ou un DTO : description, exemple, contraintes affichées (
@Schema(description = "...", example = "...")). Vient compléter ce que springdoc déduit déjà des annotations Bean Validation présentes sur le DTO (@NotBlank,@Min…).- @ApiResponse(s)
Documente les réponses possibles d'un endpoint au-delà du cas de succès :
@ApiResponses({ @ApiResponse(responseCode = "404", description = "Produit introuvable") }). springdoc ne peut pas deviner les codes d'erreur possibles à partir du seul code Java : il faut les déclarer explicitement pour qu'ils apparaissent dans la documentation.- GroupedOpenApi
Bean qui permet de définir plusieurs documentations distinctes pour une même application (ex. API publique vs API interne), chacune filtrée par package ou par motif d'URL, chacune avec sa propre page Swagger UI.
Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.