TL;DR : SmallRye OpenAPI dans Quarkus, c'est comme avoir un stagiaire super-intelligent qui écrit et met à jour votre documentation API pendant que vous codez. Plongeons dans la façon de faire fonctionner cette magie !
1. Qu'est-ce que l'OpenAPI et pourquoi l'utiliser : Parce que "ça marche" ne suffit pas
Avant de plonger dans le sujet, parlons de pourquoi nous nous soucions de la documentation API. Bien sûr, vous pourriez dire à vos utilisateurs de "se débrouiller", mais c'est à peu près aussi utile qu'une théière en chocolat.
OpenAPI (anciennement connu sous le nom de Swagger) est la référence cool pour décrire les API RESTful. C'est une spécification qui vous permet de décrire l'ensemble de votre API, y compris :
- Les points d'accès disponibles et les opérations
- Les paramètres d'opération pour l'entrée et la sortie
- Les méthodes d'authentification
- Les informations de contact, la licence, les conditions d'utilisation et d'autres informations
Pourquoi s'en soucier ? Eh bien, imaginez essayer d'utiliser une API sans documentation. C'est comme essayer de monter un meuble IKEA sans instructions – théoriquement possible, mais susceptible de se terminer en larmes et en un tas de bois de forme étrange.
2. SmallRye OpenAPI et Quarkus : Un duo parfait pour les développeurs
Voici SmallRye OpenAPI, le Robin du Batman qu'est Quarkus. C'est une implémentation de la spécification OpenAPI qui s'intègre parfaitement avec Quarkus, vous permettant de générer des documents OpenAPI à partir de votre code automatiquement.
Voici pourquoi ce duo est l'équipe de super-héros dont votre API a besoin :
- Génération automatique des spécifications OpenAPI à partir de votre code Quarkus
- Personnalisation basée sur des annotations pour un contrôle précis
- Intégration avec Swagger UI pour une documentation API interactive
- Léger et rapide, comme tout le reste dans Quarkus
3. Configurer SmallRye OpenAPI : Moins de configuration, plus de code
Prêt à ajouter un peu de magie SmallRye à votre projet Quarkus ? Allons-y !
Tout d'abord, ajoutez la dépendance suivante à votre pom.xml :
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-smallrye-openapi</artifactId>
</dependency>C'est tout. Non, vraiment. Quarkus est tellement cool qu'il détectera et configurera automatiquement SmallRye OpenAPI pour vous. Mais si vous voulez montrer vos talents de configuration, vous pouvez ajouter quelques propriétés à votre application.properties :
quarkus.smallrye-openapi.path=/openapi
quarkus.swagger-ui.always-include=trueCela définit le chemin pour votre document OpenAPI et garantit que Swagger UI est toujours inclus, même en production. Parce que qui ne veut pas explorer les APIs en prod ? (Calmez-vous, équipe de sécurité, on plaisante... en grande partie.)
4. Annoter votre API : Faire parler votre code
Maintenant vient la partie amusante – annoter votre API pour générer une documentation riche et informative. SmallRye OpenAPI utilise un mélange d'annotations JAX-RS standard et d'annotations spécifiques à OpenAPI pour décrire votre API.
Voyons un exemple :
import org.eclipse.microprofile.openapi.annotations.Operation;
import org.eclipse.microprofile.openapi.annotations.media.Content;
import org.eclipse.microprofile.openapi.annotations.media.Schema;
import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
import org.eclipse.microprofile.openapi.annotations.tags.Tag;
@Path("/api/books")
@Produces(MediaType.APPLICATION_JSON)
@Consumes(MediaType.APPLICATION_JSON)
@Tag(name = "Book Resource", description = "Book operations")
public class BookResource {
@GET
@Operation(summary = "Get all books", description = "Returns a list of all books")
@APIResponse(responseCode = "200", description = "Successful operation",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Book.class)))
public List<Book> getAllBooks() {
// Implementation
}
@POST
@Operation(summary = "Create a book", description = "Creates a new book")
@APIResponse(responseCode = "201", description = "Book created",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Book.class)))
public Response createBook(Book book) {
// Implementation
}
}Dans cet exemple, nous utilisons des annotations comme @Operation, @APIResponse, et @Tag pour fournir des informations détaillées sur nos points d'accès. Ces annotations seront captées par SmallRye OpenAPI et utilisées pour générer une documentation complète.
5. Générer des spécifications OpenAPI : Là où la magie opère
Avec votre code annoté, SmallRye OpenAPI générera automatiquement des spécifications OpenAPI aux formats JSON et YAML. Vous pouvez y accéder à :
/openapi(ou votre chemin personnalisé) pour le document OpenAPI/q/openapipour le document OpenAPI généré au format YAML/q/openapi?format=jsonpour le format JSON
Ces spécifications sont le ticket d'or pour vos consommateurs d'API. Ils peuvent les utiliser pour générer du code client, configurer des tests automatisés, ou simplement comprendre comment interagir avec votre API.
6. Swagger UI : Rendre votre API interactive
Vous vous souvenez quand nous avons activé Swagger UI plus tôt ? Il est maintenant temps de récolter les fruits. Démarrez votre application Quarkus et accédez à /q/swagger-ui. Voilà ! Vous verrez une belle représentation interactive de votre API.
Swagger UI permet aux utilisateurs de :
- Explorer les points d'accès de votre API
- Voir les modèles de requête/réponse
- Essayer des appels API directement depuis le navigateur
C'est comme un terrain de jeu pour votre API, où les développeurs peuvent tester avant de l'intégrer dans leurs applications.
7. Fonctionnalités avancées de SmallRye OpenAPI : Améliorer votre documentation
SmallRye OpenAPI ne se limite pas à la documentation de base. Il a quelques astuces dans sa manche pour des cas d'utilisation plus avancés :
Schémas personnalisés
Parfois, vous devez décrire des structures de données complexes. Utilisez l'annotation @Schema pour fournir des informations détaillées sur vos modèles :
@Schema(description = "Représente un livre dans la bibliothèque")
public class Book {
@Schema(description = "Identifiant unique du livre", example = "123e4567-e89b-12d3-a456-426614174000")
private UUID id;
@Schema(description = "Titre du livre", example = "Le Guide du voyageur galactique")
private String title;
// Autres champs et méthodes
}Schémas de sécurité
Décrivez les exigences de sécurité de votre API en utilisant l'annotation @SecurityScheme :
@SecurityScheme(securitySchemeName = "bearerAuth",
type = SecuritySchemeType.HTTP,
scheme = "bearer",
bearerFormat = "JWT")
@ApplicationPath("/api")
public class RestApplication extends Application {
// Configuration de l'application
}Exemples de requêtes/réponses
Fournissez des exemples de requêtes et de réponses pour rendre votre API encore plus conviviale :
@POST
@Operation(summary = "Créer un livre")
@APIResponse(responseCode = "201",
description = "Livre créé",
content = @Content(mediaType = "application/json",
schema = @Schema(implementation = Book.class),
examples = @ExampleObject(name = "book",
value = "{\"id\":\"123e4567-e89b-12d3-a456-426614174000\",\"title\":\"Nouveau Livre\"}")))
public Response createBook(Book book) {
// Implementation
}8. Versionner votre API : Parce que le changement est la seule constante
Les APIs évoluent, et SmallRye OpenAPI vous soutient en matière de versionnement. Vous pouvez utiliser l'annotation @Version pour spécifier différentes versions de votre API :
@Path("/api/v1/books")
@Version("1.0")
public class BookResourceV1 {
// Points d'accès V1
}
@Path("/api/v2/books")
@Version("2.0")
public class BookResourceV2 {
// Points d'accès V2
}Cela vous permet de maintenir une documentation distincte pour différentes versions de votre API, garantissant que les utilisateurs ont toujours des informations précises, quelle que soit la version qu'ils utilisent.
9. Tester vos spécifications OpenAPI : Faites confiance, mais vérifiez
Une bonne documentation n'est bonne que si elle est précise. Quarkus facilite le test de vos spécifications OpenAPI pour s'assurer qu'elles correspondent à votre implémentation réelle.
Voici un test simple pour vérifier votre document OpenAPI :
import io.quarkus.test.junit.QuarkusTest;
import org.junit.jupiter.api.Test;
import static io.restassured.RestAssured.given;
import static org.hamcrest.CoreMatchers.containsString;
@QuarkusTest
public class OpenApiTest {
@Test
public void testOpenApiEndpoint() {
given()
.when().get("/openapi")
.then()
.statusCode(200)
.body(containsString("openapi: 3.0.3"))
.body(containsString("/api/books"));
}
}Ce test garantit que votre point d'accès OpenAPI est accessible et contient le contenu attendu. Vous pouvez l'étendre pour vérifier des opérations spécifiques, des schémas ou d'autres éléments de votre documentation API.
10. Conclusion : Pourquoi SmallRye OpenAPI est votre nouveau meilleur ami
À présent, vous devriez être convaincu que SmallRye OpenAPI est comme avoir un génie de la documentation à votre service. Récapitulons pourquoi c'est un atout pour les développeurs Quarkus :
- Configuration minimale requise – c'est pratiquement du plug-and-play
- Génère automatiquement une documentation API complète
- Fournit une exploration interactive via Swagger UI
- Prend en charge des fonctionnalités avancées pour des APIs complexes
- S'intègre parfaitement à l'écosystème Quarkus
Avec SmallRye OpenAPI, vous pouvez vous concentrer sur la création d'APIs géniales pendant qu'il s'occupe de la documentation. Votre futur vous (et vos consommateurs d'API) vous remercieront.
"Une bonne documentation est comme un câlin chaleureux pour les développeurs essayant d'utiliser votre API." - Probablement un programmeur sage
Alors allez-y, annotez vos points d'accès, et laissez SmallRye OpenAPI transformer votre projet Quarkus en un phare de gloire API bien documentée. Vos utilisateurs chanteront vos louanges, votre équipe travaillera plus efficacement, et vous pourriez même apprécier d'écrire de la documentation. (D'accord, ne nous emballons pas sur ce dernier point.)
Lectures complémentaires et ressources
Vous voulez plonger plus profondément dans le monde de SmallRye OpenAPI et Quarkus ? Consultez ces ressources :
Bon codage, et que vos APIs soient toujours bien documentées !