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
Page 1 sur 11
Télécharger l'app CarmaBlog

Flux RSS

  • RSS Feed RSS - Articles
  • RSS Feed RSS - Commentaires

Articles les plus vus

  • Changer la langue de Firefox - 114 958 vues
  • Réaliser un sondage en ligne avec Google Forms / Drive / Docs - 61 734 vues
  • FAQ – Sondage en ligne avec Google Forms / Drive / Docs - 42 850 vues
  • Personnaliser Gnome 3 (Shell) - 29 154 vues
  • La signification d’URL, URI et URN - 16 043 vues
  • Java EE & CDI vs. Spring - 14 862 vues
  • Open Street Map, une meilleure carte que Google Maps? - 13 830 vues
  • Comparaison NoSQL: Couchbase et MongoDB - 13 555 vues
  • Firefox Nightly, Aurora, Beta, Desktop, Mobile, ESR & Co. - 12 745 vues
  • Une première approche du Camel d’Apache - 11 763 vues

Commentaires récents

  • Léooon sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsJ'en suis même certaine... Très bien merci beaucou…
  • Fabian Piau sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsNormalement oui ou même 100, juste assurez-vous de…
  • Léooon sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsLà est le problème, je suis loin d'avoir envoyé 20…
  • Fabian Piau sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsCela semble être une limitation liée à votre clien…
  • Léooon sur FAQ – Sondage en ligne avec Google Forms / Drive / DocsBonjour, Je rencontre acutellement un problème ave…

Articles récents

  • Flagger – Monitorer vos déploiements Canary avec Grafana - Il y a 8 mois et 1 semaine
  • Flagger – Déploiements Canary sur Kubernetes - Il y a 9 mois et 2 semaines
  • Flagger – Premiers pas avec Istio et Kubernetes - Il y a 10 mois et 4 jours
  • CoderDojo Expedia à Londres - Il y a 1 an et 7 mois
  • Etre bénévole à Devoxx4Kids - Il y a 1 an et 10 mois
  • Une migration Java 11 réussie - Il y a 2 ans et 2 mois
  • Conseils pour sécuriser votre site WordPress - Il y a 2 ans et 4 mois
  • Devoxx UK 2018 – Jour 2 - Il y a 2 ans et 9 mois
  • Devoxx UK 2018 – Jour 1 - Il y a 2 ans et 9 mois
  • TransferWise, Revolut et Monzo, une petite révolution dans le monde des expatriés et voyageurs - Il y a 3 ans et 1 mois
  • Autocomplétion pour Git - Il y a 3 ans et 9 mois
  • Swagger, la documentation API automatisée - Il y a 4 ans et 5 jours
  • Architecture Microservices – Les bonnes pratiques - Il y a 4 ans et 5 mois
  • FAQ – Sondage en ligne avec Google Forms / Drive / Docs - Il y a 4 ans et 10 mois
  • QCon London 2016 – Projet Jigsaw dans JDK 9 – La modularité arrive sur Java - Il y a 4 ans et 10 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 agilité android bash blog bonnes pratiques cache cloud conférence css devoxx docker docs drive développeur eclipse extreme programming firefox flagger forms google helm hibernate informatique intégration continue istio java jug kubernetes londres mobilité informatique métier outil panorama partage performance plugin programmeur qcon script société spring 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 (7)
  • Programmation agile (29)
  • Technologie (44)

Archives

  • 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 - 2021
Tous droits réservés | Haut ↑