Agilité, Développement Java, Nouvelles technologies et plus…
  • rss
  • Accueil
  • Management
  • Programmation agile
  • Technologie
  • Linux
  • Evénement
  • App Android
  • Contact
  • A propos de l'auteur
  • English
  • Francais

Swagger, la documentation API automatisée

Fabian Piau | mercredi 1 mars 2017 - 21:36
  • Imprimer
  • Twitter
  • LinkedIn
  • Facebook
  • Pocket

 English version available

A l’heure où les projets informatiques se basent la plupart du temps sur une architecture orientée microservices, il n’est pas étonnant que les différents microservices soient développés et maintenus par des équipes différentes.

Chaque service fournit une API (privée ou public) qui permet de communiquer avec le monde extérieur tout en garantissant l’intégrité de ses données. De multiples appels imbriqués entre les microservices permettent de réaliser un traitement plus complexe. Il est très important d’avoir une documentation à jour pour chacune de vos API. Qui n’a jamais entendu un développeur dire à un autre « Cette doc n’a pas été mise à jour depuis des mois, regarde le code directement! ».

Swagger logo

Swagger UI se conforme à cette affirmation. Il suffit d’ajouter des annotations précises dans votre code et le framework s’occupera de générer de manière semi-automatique toute la documentation de votre API. ‘Semi-automatique’ car il ne peut pas écrire la documentation métier, vous devez donc l’écrire vous-même, un peu comme si vous écrivez de la Javadoc.

La documentation générée par Swagger est donc mise à jour en même temps que le code. Par exemple, si vous ajoutez un nouveau paramètre à une méthode exposée, celui-ci sera automatiquement pris en compte et documenté avec les annotations adéquates. La documentation n’est pas seulement un fichier HTML statique, elle permet de faire office de client HTTP (il n’y a pas besoin d’avoir Postman installé par exemple) pour tester les différentes méthodes exposées par l’API.

Vous pouvez regarder l’application exemple officielle (Petstore) pour avoir un accès aux différentes fonctionnalités supportées, par exemple l’authentification OAuth2.0 est supportée.

Exemple d'application avec Swagger

Exemple d'application avec Swagger

Cerise sur le gâteau si vous utilisez Spring MVC dans votre application, le projet SpringFox (surcouche Swagger) rend l’intégration de Swagger très simple. En moins d’une heure, vous devriez être capable de générer la documentation de votre API. Ensuite, vous pourrez ajouter des annotations optionnelles pour la rendre plus complète.

En adoptant Swagger sur l’ensemble de vos microservices, il est fort à parier que la communication entre vos différentes équipes s’améliore. Désormais, vous n’aurez qu’un seul point d’entrée, oubliez donc la page wiki mal-documentée qui avait tendance à prendre la poussière… En vous souhaitant une bonne documentation!

Articles similaires

microservices-legoArchitecture Microservices – Les bonnes pratiques devoxxDevoxx UK 2018 – Jour 2 people-linkedFaire du REST social avec HATEOAS webservicesAPI, REST, JSON, XML, HTTP, URI… Vous parlez quelle langue en fait?
Commentaires
2 Commentaires »
Catégories
Programmation agile
Tags
bonnes pratiques, microservices, outil, spring
Flux rss des commentaires Flux rss des commentaires

QCon London 2016 – Spring Framework 5 – Preview et Roadmap

Fabian Piau | mardi 15 mars 2016 - 23:49
  • Imprimer
  • Twitter
  • LinkedIn
  • Facebook
  • Pocket

 English version available

Juergen Hoeller, le co-fondateur du Framework Spring a fait une présentation la semaine dernière au QCon London.

QCon London 2016 - Spring Framework 5 - Preview & Roadmap

QCon London 2016 - Spring Framework 5 - Preview & Roadmap


Commençons par un bref historique, le Framework Spring a été créé en 2002 avec une première version en 2004 (oui, c’était il y a 12 ans!), un bon bout de temps pour un framework qui est encore largement utilisé et en cours de développement. Depuis sa création, l’adoption et le nombre de projets au sein de Spring n’ont jamais cessé de croître. Au début, Spring a été créé pour gérer des POJOs dans un conteneur léger en utilisant l’injection de dépendances (en suivant le principe d’Inversion de contrôle), Spring était une alternative aux conteneurs JEE dits lourds tels que GlassFish ou WebSphere.


Spring est maintenant devenu un ensemble de projets disponibles pour satisfaire toutes les exigences du développement d’une application. Spring est comme un jeu de Legos, vous pouvez sélectionner et assembler ces sous-projets comme des briques pour construire quelque chose de plus grand.

  • Imaginez que vous avez besoin d’utiliser une base de données, vous pouvez utiliser Spring Data
  • Vous avez besoin d’une application sécurisée avec un système d’authentification, il vous suffit d’utiliser Spring Security
  • Vous voulez être en mesure de vous connecter à votre application par le biais des réseaux sociaux, Spring Social est là pour vous
  • Et ainsi de suite

Vous pouvez jeter un oeil à la liste complète des projets Spring.


Spring 4.3

Avant de passer à Spring 5, Juergen a parlé de Spring 4. Quand j’écris cet article, la version actuelle est 4.2.5. Une release candidate (RC) de Spring 4.3 sera disponible en mars 2016 suivie d’une General availability (GA) en mai 2016. Cette version comprendra quelques changements pratiques:

  • Dans le framework Spring core:
    L’annotation @autowired utilisée pour injecter une dépendance sera implicite et sera donc désormais optionnelle
  • Dans Spring MVC (fait partie du core):
    La déclaration d’un contrôleur MVC est simplifiée. Avant, value était le nom de l’attribut à utiliser:

    @RequestMapping(value = '/mypath', method = RequestMethod.POST)
    

    Désormais, nous allons utiliser un nom plus significatif path:

    @RequestMapping(path = '/mypath', method = RequestMethod.POST)
    

    De nouvelles annotations font leur apparition, des raccourcis pour éviter de spécifier la méthode HTTP. Le nom de l’attribut étant facultatif, la déclaration du contrôleur devient extrêmement simple.

    @PostMapping('/mypath')
    

    Et l’équivalent pour un GET

    @GetMapping('/mypath')
    


Spring 5.0 annoncé

Ensuite, Juergen a annoncé que Spring 5.0 sera disponible dans le courant de l’année 2017 et compatible avec le JDK 8 et 9. Sur la roadmap, la version AG devrait être disponible en Mars 2017 (en même temps que le JDK 9 sera publié). Dans le cas où la release du JDK 9 serait retardée, Spring 5.0 le sera probablement aussi.


Quelles sont les principales nouveautés de Spring 5?

Il y a 3 thèmes clés qui vont modifier le framework:

  • JDK 9 et les modules Jigsaw
  • Servlet 4.0 et HTTP/2
  • Architecture réactive


JDK 9 et l’utilisation de Jigsaw

En une phrase, Jigsaw apporte de la modularité au JDK. Le JDK est divisé en modules et vous pouvez utiliser seulement ceux dont vous avez besoin pour créer votre application.

Le JDK sera livré avec un ensemble de modules, mais vous pouvez également définir vos propres modules. Pour définir un module, vous devez créer un fichier module-info.java:

module my.app.db {
  requires java.sql;
  requires spring.jdbc;
}

A l’intérieur d’un module, vous spécifiez les modules dont vous avez besoin avec le mot-clé requires. Les modules gèrent les dépendances transitives, un peu comme Maven. Si j’utilise le module my.app.db ci-dessus, je peux accéder à l’ensemble des classes venant du module java.sql. Le principal avantage est que cela rend votre application plus modulaire en reposant sur un sous-ensemble de modules au lieu d’un JDK complet.

Tous les jars de Spring 5 seront packagés avec ces métadonnées Jigsaw, le nom du module suivra les conventions déjà utilisées sur le repo Maven Central afin d’éviter toute confusion (spring-context, spring-jdbc, spring-webmvc…). Il sera très facile de construire vos applications en spécifiant les modules Spring dont vous avez besoin.


HTTP/2

HTTP/1.1 est un vieux protocole (1999) et souffre de limitations. Dans le monde du front-end, nous utilisons des solutions de contournement, mais ce n’est pas l’idéal. Par exemple, pour éviter de surcharger le serveur avec de multiples requêtes lorsqu’une page contient beaucoup d’images, nous utilisons des sprites CSS (c.-à-d. combiner ces images dans un seul fichier que nous « découpons » ensuite côté client via CSS). Avec HTTP/2, le protocole est plus rapide car il permet des requêtes simultanées. Il y a d’autres avantages que vous pouvez lire sur la FAQ HTTP/2 Frequently Asked Questions.

Comme l’a déclaré Juergen, « Nous devons adopter HTTP/2 dans les terres de Java! »

Pour ce faire, Spring 5 utilisera la dernière version de la librairie Servlet, Servlet 4.0 qui:

  • Impose le support pour HTTP/2 dans des conteneurs de servlet
  • Contient des fonctionnalités pour prioriser les Streams et le push de ressources via une API


Programmation réactive

Un autre point fort a été l’annonce de la création d’un nouveau projet Spring appelé Spring Reactive. Ce sera un Spring MVC-like avec des endpoints basés sur une fondation réactive.

  • Réutilisation de style de modèle de programmation de Spring MVC
  • Mais en acceptant ou en retournant des reactive streams (par exemple, Mono – 1 élément, Flux – liste d’éléments)

Spring Reactive sera basé sur le Project Reactor, un ensemble de bibliothèques pour construire des applications réactives cloud-ready sur la JVM. Ce nouveau projet ne sera pas indépendant et sera inclus dans le noyau Spring Framework à un moment donné.

Juergen nous rappelle que le « Reactive arrive »:

  • Pas de blocage de thread
  • Les drivers réactif pour les bases de données deviennent disponibles (PostgreSQL, Mongo, Couchbase…)
  • Il y a aussi des clients HTTP réactifs (Netty, Jetty, OkHttp…)

Note pour moi-même et peut-être aussi pour vous, il est important de se documenter sur le Reactive Programming et se familiariser avec les concepts. Il y a de grandes chances qu’il se démocratise dans les années qui viennent.


Enfin, Spring 5 utilisera toutes les dernières fonctionnalités introduites avec Java 8:

  • Lambdas, références de méthode, méthodes par défaut dans les interfaces
  • Nouvelles classes utilitaires: java.util.Optional, java.util.function, java.util.stream


Evidemment, Spring 5 nécessite Java 8. Si votre projet utilise encore une ancienne version, vous devrez vous contenter de Spring 4.X. La bonne nouvelle est que Spring 4 aura un support étendu jusqu’en 2020, de sorte que vous aurez encore un peu de temps pour migrer!


Les slides de la présentation sont disponibles sur le site de QCon.

Articles similaires

java-9QCon London 2016 – Projet Jigsaw dans JDK 9 – La modularité arrive sur Java Java 11Une migration Java 11 réussie Java EE vs SpringJava EE & CDI vs. Spring devoxxDevoxx UK 2018 – Jour 1
Commentaires
Pas de Commentaires »
Catégories
Evénement
Tags
qcon, spring
Flux rss des commentaires Flux rss des commentaires
Page 1 sur 212
Télécharger l'app CarmaBlog

Flux RSS

  • Flux RSS RSS - Articles
  • Flux RSS RSS - Commentaires

Articles les plus vus

  • Changer la langue de Firefox - 115 579 vues
  • Réaliser un sondage en ligne avec Google Forms / Drive / Docs - 63 166 vues
  • FAQ – Sondage en ligne avec Google Forms / Drive / Docs - 52 403 vues
  • Personnaliser Gnome 3 (Shell) - 30 017 vues
  • La signification d’URL, URI et URN - 17 251 vues
  • Java EE & CDI vs. Spring - 15 442 vues
  • Open Street Map, une meilleure carte que Google Maps? - 14 648 vues
  • Comparaison NoSQL: Couchbase et MongoDB - 14 082 vues
  • Firefox Nightly, Aurora, Beta, Desktop, Mobile, ESR & Co. - 13 087 vues
  • API, REST, JSON, XML, HTTP, URI… Vous parlez quelle langue en fait? - 12 718 vues

Commentaires récents

  • Pauline sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsMerci Fabian, mais le but étant que nos clients pu…
  • Fabian Piau sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsProbablement mais ces options sont en général paya…
  • Pauline sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsBonjour Fabian, Merci de votre retour, oui j'avais…
  • Fabian Piau sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsBonjour Pauline, ce n'est pas possible de créer un…
  • Pauline sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsBonjour, Je suis en train de créer un Google Forms…

Articles récents

  • Comment écrire un article de blog? En tout cas à ma façon! - Il y a 3 mois et 2 semaines
  • Attaques de robots: vous n’êtes pas seul… - Il y a 1 an et 11 mois
  • Flagger – Monitorer vos déploiements Canary avec Grafana - Il y a 2 ans et 8 mois
  • Flagger – Déploiements Canary sur Kubernetes - Il y a 2 ans et 10 mois
  • Flagger – Premiers pas avec Istio et Kubernetes - Il y a 2 ans et 10 mois
  • CoderDojo Expedia à Londres - Il y a 3 ans et 7 mois
  • Etre bénévole à Devoxx4Kids - Il y a 3 ans et 10 mois
  • Une migration Java 11 réussie - Il y a 4 ans et 2 mois
  • Conseils pour sécuriser votre site WordPress - Il y a 4 ans et 5 mois
  • Devoxx UK 2018 – Jour 2 - Il y a 4 ans et 9 mois
  • Devoxx UK 2018 – Jour 1 - Il y a 4 ans et 9 mois
  • Wise, Revolut et Monzo, une petite révolution dans le monde des expatriés et voyageurs - Il y a 5 ans et 1 mois
  • Autocomplétion pour Git - Il y a 5 ans et 10 mois
  • Swagger, la documentation API automatisée - Il y a 6 ans et 2 semaines
  • Architecture Microservices – Les bonnes pratiques - Il y a 6 ans et 5 mois
Offre moi un café

Langue

  • Français
  • English

Suivez-moi!

Suivez-moi sur Linkedin
Suivez-moi sur Twitter
Suivez-moi sur Stackoverflow
Suivez-moi sur Github
Suivez-moi sur Rss
Link to my Contact

Abonnement email

Saisissez votre adresse email pour être informé des nouveaux articles.

Étiquettes

.net agile agilité android bash blog bonnes pratiques cache cloud conférence css devoxx docker développeur eclipse extreme programming firefox flagger google helm hibernate informatique intégration continue istio java jug kubernetes londres mobilité informatique métier outil panorama partage performance plugin programmeur script société spring sécurité tdd test ubuntu windows wordpress

Liens

  • Blog Ippon Technologies
  • Blog Publicis Sapient
  • Blog Zenika
  • Classpert
  • CommitStrip
  • Coursera
  • Le Touilleur Express
  • Les Cast Codeurs Podcast
  • OCTO talks !
  • The Twelve-Factor App

Catégories

  • Evénement (15)
  • Linux (3)
  • Management (8)
  • Programmation agile (29)
  • Technologie (45)

Archives

  • décembre 2022 (1)
  • avril 2021 (1)
  • juin 2020 (1)
  • mai 2020 (2)
  • juillet 2019 (1)
  • mai 2019 (1)
  • décembre 2018 (1)
  • octobre 2018 (1)
  • juin 2018 (1)
  • mai 2018 (1)
  • janvier 2018 (1)
  • mai 2017 (1)
  • mars 2017 (1)
  • octobre 2016 (1)
  • avril 2016 (2)
  • mars 2016 (1)
  • novembre 2015 (1)
  • mai 2015 (1)
  • février 2015 (1)
  • décembre 2014 (1)
  • novembre 2014 (1)
  • septembre 2014 (2)
  • août 2014 (1)
  • juillet 2014 (2)
  • juin 2014 (1)
  • avril 2014 (1)
  • mars 2014 (1)
  • février 2014 (2)
  • janvier 2014 (1)
  • décembre 2013 (1)
  • novembre 2013 (1)
  • octobre 2013 (3)
  • septembre 2013 (5)
  • juillet 2013 (1)
  • juin 2013 (1)
  • mai 2013 (1)
  • avril 2013 (1)
  • mars 2013 (2)
  • février 2013 (1)
  • janvier 2013 (2)
  • décembre 2012 (2)
  • octobre 2012 (1)
  • septembre 2012 (1)
  • juillet 2012 (1)
  • mai 2012 (1)
  • avril 2012 (1)
  • mars 2012 (1)
  • février 2012 (1)
  • janvier 2012 (2)
  • décembre 2011 (1)
  • novembre 2011 (2)
  • octobre 2011 (2)
  • septembre 2011 (1)
  • juillet 2011 (1)
  • juin 2011 (2)
  • avril 2011 (1)
  • mars 2011 (1)
  • février 2011 (1)
  • janvier 2011 (2)
  • novembre 2010 (2)
  • septembre 2010 (1)
  • août 2010 (1)
  • juillet 2010 (1)
  • juin 2010 (1)
  • mai 2010 (1)
  • avril 2010 (1)
  • mars 2010 (1)
  • février 2010 (1)
  • décembre 2009 (1)
  • novembre 2009 (1)
  • octobre 2009 (2)
  • septembre 2009 (2)
  • août 2009 (3)
  • juillet 2009 (1)
  • juin 2009 (2)
Suivez-moi sur Twitter
Suivez-moi sur Linkedin
Suivez-moi sur Stackoverflow
Suivez-moi sur Rss
Link to my Contact
Suivez-moi sur Github
 
Fabian Piau | © 2009 - 2023
Tous droits réservés | Haut ↑