Création d’une API REST en Spring Boot avec Open API 3.0

De Clémence Boulay dans Technique

2 juil 2018

Bonjour, aujourd’hui nous allons swagger sur la vague des APIs REST avec la création d’un serveur d’API en Spring Boot avec Open API 3 et les outils Swagger.

 

Design de l’API

 

La méthodologie : l’approche « contract first »

Développeurs, je sais que les lignes de codes vous brûlent les doigts, mais vous allez devoir patienter un peu. Nous allons en effet opter pour une méthodologie « contract first » pour designer cette API. Cette approche relativement récente consiste avant toute chose à définir un contrat entre le fournisseur et le client de l’API. Il faut donc commencer par écrire une spécification détaillée avant de commencer tout développement. Ce contrat peut être établi de façon itérative, en commençant par des URIs de base et des exemples d’échanges, puis en l’étoffant au fur et à mesure, en collaboration avec les différents acteurs du projet. C’est une fois seulement que le contrat est stable que les développements pourront débuter.

C’est bien joli et conceptuel, mais à quoi ça sert ?

  • Tester une API qui n’est pas encore développée
    Tout le monde peut faire joujou avec l’API avant même qu’elle ne soit développée
  • Paralléliser les développements
    Une fois le contrat d’interface stable, on peut non seulement commencer les développements de l’API fournisseur, mais également ceux des applications qui vont consommer les WebServices, les tests unitaires, etc.
  • Un seul format de description unique pour plusieurs acteurs
    Développeurs, testeurs, chefs de projets et autres profils collaborent et se mettent d’accord sur une spécification claire et facilement lisible pour tous. La documentation générée pourra être utilisée à la fois pour les acteurs internes (équipe projet) et externes (clients).
  • Un seul format de description unique pour plusieurs actions
    • Génération de documentation
    • Génération du code serveur
    • Génération du code client
    • Pilotage de tests automatisés
    • Déploiements automatisée
    • Etc.
  • Prendre du recul, le temps de la conception et se recentrer sur les objectifs de l’API
    Ne pas foncer tête baissée dans le code mais prendre le temps de bien concevoir l’API, de réfléchir à un vocabulaire et une structure comprise et approuvée par les différents acteurs.

Cette méthode possède beaucoup d’avantages, mais demande de la rigueur. En cas d’évolutions à faire dans l’API, il faudra réitérer ce processus en incrémentant le numéro de version de l’API et en redéfinissant un nouveau contrat d’échange entre fournisseur et clients.

 

Les outils : Open API 3.0 et Swagger Hub

 

Open API 3.0

La toute dernière spécification Open API 3.0 (sortie en 2017) est un format standard qui permet de décrire simplement des APIs REST. Cette description est établie dans un format json ou yaml, et permet de définir :

  • Les paramètres globaux de votre API (nom, serveurs, sécurité, informations générales…)
  • Chacun des services REST qui la compose (URI, verb, request, response, …) mais aussi la documentation associée (résumés, descriptions, exemples, …)

Elle succède et remplace le standard Swagger 2.0, avec des changements structurels importants et de nouvelles fonctionnalités qui améliorent sa réutilisabilité. Je ne vais pas vous lister ici toutes les nouveautés qui déjà sont présentées dans cet article du SwaggerBlog.

Je vous invite également à visionner cette conférence très intéressante sur le sujet présentée au Devoxx 2018 par Sébastien Lecacheur et Grégory Bloquel. Vous y trouverez les explications des principaux changements, illustrés de façon claire par des exemples.

Même si ce nouveau standard marque un tournant dans la définition des APIs, il est dans la continuité de son prédécesseur. Pas de raison de vous inquiéter, vous pourrez donc continuer à utiliser les indispensables outils Swagger (éditeur, UI, hub, …), même si tous ne sont pas encore prêts à l’heure où je vous parle.

 

Swagger Hub

Pour décrire notre API, nous allons utiliser le Swagger Hub. Pour les novices, il s’agit d’une plateforme qui permet de centraliser vos différentes APIs, de les designer, de collaborer et de les partager. Elle rassemble les différents outils Swagger en un seul point d’entrée, et réuni toutes vos définitions d’APIs au même endroit.


Swagger Hub

 

Une fois votre API créée, vous pouvez l’éditer et la décrire dans le Swagger Editor. Voici un exemple d’API d’inventaire basique réalisée avec Swagger Hub sur les base d’Open API 3.0 :

Cette API est disponible ici si vous voulez jouer avec. Elle n’est pas implémentée, elle n’est qu’à l’étape « contrat », mais l’outil permet déjà de la tester grâce aux formats et exemples décrits.

 

Génération du serveur Spring Boot

Open API 3.0 est sorti très récemment, et les outils ne sont pas encore tout à fait prêts. Si vous avez déjà designé des APIs avec Swagger 2.0, vous savez qu’il est possible en un clic de générer le code serveur et client de votre API.

Malheureusement, cette fonctionnalité n’est pas encore compatible avec Open API 3.0. Mais heureusement, en attendant sa sortie, il existe une alternative : le projet openapi-generator.

Téléchargez le projet à partir du GitHub et suivez les instructions. Attention à bien choisir une version compatible Open Api 3.0 (voir le tableau de compatibilité).

Après avoir buildé le projet, une ligne de commande suffira pour générer votre serveur Spring Boot REST à partir de votre spécification yaml :

1
java -jar modules\openapi-generator-cli\target\openapi-generator-cli.jar generate -i monSwagger.yaml -g spring -o c:\temp\spring_api_client

 

Swagger code generator

 

Un petit clic droit sur le projet et démarrage du serveur embarqué Spring Boot et le tour et joué :

Swagger UI

Vous pouvez ensuite tester vos services directement dans l’UI générée par Swagger :

Swagger test API

Une fois l’étape de description de l’API réalisée, vous pouvez constater que la génération du projet se fait très simplement, et qu’avec ces outils il est très pratique de tester les différents WebServices.

Il ne reste maintenant plus qu’à implémenter le métier de l’API, alors c’est parti, prêt, feu codez :) !

Commentaire

8 − deux =

iMDEO recrute !

REJOIGNEZ-NOUS

A la recherche de nouveaux talents (développeurs web et mobile, chefs de projet,...)

Voir les annonces