> ## Content Index
> Fetch the complete content index at: https://www.sfeir.dev/llms.txt
> Use this file to discover other available public pages before exploring further.
# Mettre en place la documentation OpenAPI dans une application Quarkus
- URL: https://www.sfeir.dev/back/mettre-en-place-la-documentation-openapi-dans-une-application-quarkus/
- Published: 2026-05-21T14:30:04.000Z
- Updated: 2026-05-21T14:30:04.000Z
- Description: Mettre en place une documentation d’API claire n’est plus une option. Avec Quarkus, SmallRye OpenAPI et Swagger UI, générez automatiquement une documentation exploitable et testable. Une base solide pour construire des APIs propres et durables.
- Author: Erwan Le Tutour
- Tags: Back, Java, quarkus, Documentation
Dans cette première étape de la série sur [Quarkus](https://www.sfeir.dev/quarkus-definition/) (qui se veut un reflet de celle sur [Spring Boot](https://www.sfeir.dev/back/il-etait-une-fois-spring-boot/)), on met en place une documentation d’[API REST](https://www.sfeir.dev/rest-definition/) 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` :
```xml
io.quarkus
quarkus-smallrye-openapi
io.quarkus
quarkus-rest-jackson
```
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 :
```bash
mvn quarkus:dev
```
Vous pouvez accéder à l’interface Dev UI via :
```text
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.
```properties
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
```java
@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.
```java
@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 :
```bash
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
curl "http://localhost:8080/api/tavern/greeting?name=Erwan"
```
Exemple pour une commande :
```curl
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 :
[GitHub - ErwanLT/quarkus-demo: Demo project for quarkus possibilityDemo project for quarkus possibility. Contribute to ErwanLT/quarkus-demo development by creating an account on GitHub.GitHubErwanLT](https://github.com/ErwanLT/quarkus-demo?ref=sfeir.dev)