Mettre en place la documentation OpenAPI dans une application Quarkus

Dans cette première étape de la série sur Quarkus (qui se veut un reflet de celle sur Spring Boot), on met en place une documentation d’API REST propre et exploitable avec SmallRye OpenAPI et Swagger UI. On s’appuie sur un exemple concret : une API de taverne médiévale, avec un endpoint de salutation et un endpoint de commande.

Dans un projet réel, une API non documentée devient rapidement difficile à exploiter, que ce soit pour les autres développeurs, les équipes frontend, ou simplement pour tester ses propres endpoints. Une documentation claire, accessible et interactive n’est donc pas un luxe, mais une base de travail essentielle.

L’objectif est double :

Générer automatiquement un OpenAPI JSON
Exposer une UI Swagger pour explorer et tester l’API

Ajouter les dépendances nécessaires

Dans le module doc-tutorial, la documentation OpenAPI s’active via l’extension quarkus-smallrye-openapi. On ajoute également le support REST + JSON.

Il existe deux façons de procéder, selon votre manière de travailler.

Approche classique (via le `pom.xml`)

Extrait du pom.xml :

<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-rest-jackson</artifactId>
</dependency>

Extrait du pom.xml

Cette approche reste la plus directe et la plus maîtrisée, notamment dans un contexte de projet structuré ou en environnement d’intégration continue.

Approche Quarkus Dev UI

Quarkus propose également une manière plus interactive d’ajouter des extensions via la Dev UI, accessible en mode développement.

Une fois l’application lancée avec :

mvn quarkus:dev

Vous pouvez accéder à l’interface Dev UI via :

http://localhost:8080/q/dev-ui

Depuis cette interface, il est possible de rechercher et d’ajouter des extensions (dont SmallRye OpenAPI) en quelques clics, sans modifier manuellement le pom.xml.

L'extension SmallRye OpenAPI dans la Dev UI

Cette approche est particulièrement pratique en phase de découverte ou de prototypage rapide.

Configurer l’accès à OpenAPI et Swagger UI

Une fois les dépendances en place, quelques propriétés suffisent à exposer la documentation.

quarkus.smallrye-openapi.path=/openapi
quarkus.swagger-ui.always-include=true

quarkus.smallrye-openapi.info-title=Tavern REST API
quarkus.smallrye-openapi.info-version=1.0.0
quarkus.smallrye-openapi.info-description=Exemple d'API REST dans une taverne medievale.

Quarkus se charge ensuite de générer automatiquement la spécification OpenAPI en scannant les endpoints et les annotations présentes dans le code.

Définir les endpoints REST

L’API expose deux endpoints dans TavernApiResource :

GET /api/tavern/greeting
POST /api/tavern/order

Les annotations OpenAPI permettent d’enrichir la documentation générée :

@Operation décrit l’intention métier
@APIResponse précise les réponses possibles
@Parameter documente les paramètres d’entrée (query, path, header…)
@QueryParam permet de récupérer un paramètre de requête dans l’URL

@GET
@Path("/greeting")
@Operation(summary = "Saluer un aventurier", description = "Retourne un message d'accueil de l'aubergiste.")
@APIResponse(
        responseCode = "200",
        description = "Message d'accueil",
        content = @Content(schema = @Schema(implementation = TavernGreetingResponse.class))
)
public TavernGreetingResponse greeting(
        @Parameter(
          description = "Nom de l'aventurier à saluer",
          example = "Arthas"
        )
        @QueryParam("name") String name) {
    return tavernService.greeting(name);
}

Extrait de notre controller

Enrichir la documentation avec les DTO

La qualité de la documentation dépend aussi des modèles exposés. Les DTO peuvent être annotés avec @Schema pour préciser leur structure et fournir des exemples.

@Schema(description = "Commande a la taverne")
public record TavernOrderRequest(
        @Schema(description = "Objet commande", example = "Healing Potion")
        String item,
        @Schema(description = "Quantite", example = "2")
        int quantity
) {
}

Une commande à la taverne

Cette étape améliore considérablement la lisibilité dans Swagger UI, notamment pour les consommateurs de l’API.

On peut aller plus loin en ajoutant des contraintes de validation (@NotNull, etc.), qui seront également reflétées dans la documentation.

Lancer l’application

Le mode développement de Quarkus permet un démarrage rapide avec rechargement à chaud :

mvn quarkus:dev

Accéder à la documentation générée

Une fois l’application lancée, deux points d’entrée sont disponibles :

OpenAPI JSON : http://localhost:8080/openapi
Swagger UI : http://localhost:8080/q/swagger-ui

Swagger UI permet de visualiser les endpoints, d’examiner les modèles de données et d’exécuter des requêtes directement depuis le navigateur.

Notre API documentée dans son interface swagger

Tester rapidement les endpoints

Exemple d’appel pour l'endpoint de salutation :

curl "http://localhost:8080/api/tavern/greeting?name=Erwan"

Exemple pour une commande :

curl -X POST http://localhost:8080/api/tavern/order \
  -H "Content-Type: application/json" \
  -d '{"item":"Healing Potion","quantity":2}'

Conclusion

Avec un minimum de configuration et quelques annotations bien placées, Quarkus permet de produire une documentation d’API complète, lisible et interactive.

Ce socle facilite non seulement le développement, mais aussi la collaboration et la maintenance à long terme.

Tout le code relatif à cet article peut être trouvé ici :