Agility, Java programming, New technologies and more…
  • rss
  • Home
  • Management
  • Agile Programming
  • Technology
  • Linux
  • Event
  • Android app
  • Contact
  • About the author
  • English
  • Francais

Swagger, the automated API documentation

Fabian Piau | Wednesday March 1st, 2017 - 09:36 PM
  • Print
  • Twitter
  • LinkedIn
  • Facebook
  • Pocket

 Version française disponible

IT projects nowadays are mostly based on a microservice oriented architecture, it is not surprising that the different microservices are developed and maintained by different teams.

Each service provides an API (private or public) that allows the communication with the outside world while guaranteeing its data integrity. Multiple nested calls between microservices make it possible to do more complex processing. It is very important to have an up-to-date documentation for each of your APIs. Who has never heard a developer say to another “This doc has not been updated for months, look at the code directly!”.

Logo Swagger

Swagger UI complies with this assertion. Simply annotate your code and the framework will semi-automatically generate all your API documentation. I use ‘semi-automatic’ because Swagger cannot guess the business side of your documentation, so you have to write it yourself in a similar way that you are writing Javadoc.

The documentation generated by Swagger is updated at the same time as the code is. For instance, if you add a new parameter to a method that is exposed, it will be automatically taken into account and documented with the appropriate annotations. The documentation is much more than a static HTML file, it allows to act as an HTTP client (there is no need to have Postman installed for example) to test the various methods exposed by the API.

You can take a look at the official sample application (Petstore) and see by yourself the various supported features, for example OAuth2.0 authentication is supported.

Example with Swagger (Petstore)

Example with Swagger (Petstore)

If you use Spring MVC in your application, the SpringFox project (Swagger wrapper) makes Swagger integration very simple. In less than an hour, you should be able to generate your API documentation. Then you can add optional annotations to make it even more complete.

By adopting Swagger on all your microservices, it is a good bet that the communication between your different teams will improve. You will have a unique entry point and you can forget that dusty wiki page that was updated once in a while… Wishing you good documentation!

Related posts

microservices-legoMicroservices architecture – Best practices devoxxDevoxx UK 2018 – Day 2 people-linkedDoing some social REST with HATEOAS webservicesAPI, REST, JSON, XML, HTTP, URI… What language do you speak?
Categories
Agile programming
Tags
best practices, microservices, tool, spring
Comments rss
Comments rss

« Microservices architecture – Best practices Autocomplete for Git »

Download CarmaBlog App

RSS feeds

  • RSS Feed RSS - Posts
  • RSS Feed RSS - Comments

Most viewed posts

  • Changing the language in Firefox - 114,911 views
  • Using Google Forms / Drive / Docs to create an online survey - 61,517 views
  • FAQ – Online survey with Google Forms / Drive / Docs - 41,246 views
  • Customizing Gnome 3 (Shell) - 29,097 views
  • The meaning of URL, URI, URN - 15,915 views
  • Java EE & CDI vs. Spring - 14,815 views
  • Open Street Map, better map than Google Maps? - 13,775 views
  • Comparing NoSQL: Couchbase & MongoDB - 13,522 views
  • Firefox Nightly, Aurora, Beta, Desktop, Mobile, ESR & Co. - 12,725 views
  • First steps with Apache Camel - 11,722 views

Recent Comments

  • Saint hilaire albert on FAQ – Online survey with Google Forms / Drive / Docsmerci beaucoup
  • Fabian Piau on FAQ – Online survey with Google Forms / Drive / DocsNon, ce n’était pas la bonne pratique effectivemen…
  • Saint hilaire albert on FAQ – Online survey with Google Forms / Drive / Docsah, alors je crois avoir trouvé : mon lien se term…
  • Fabian Piau on FAQ – Online survey with Google Forms / Drive / DocsJe n'arrive pas à reproduire car si vous cliquez s…
  • Saint hilaire albert on FAQ – Online survey with Google Forms / Drive / Docsje vais tenter d'être plus précis : j'envoie un li…

Recent posts

  • Flagger – Monitor your Canary deployments with Grafana - 6 months and 3 weeks ago
  • Flagger – Canary deployments on Kubernetes - 8 months and 10 hours ago
  • Flagger – Get Started with Istio and Kubernetes - 8 months and 2 weeks ago
  • Expedia CoderDojo in London - 1 year and 5 months ago
  • Volunteering at Devoxx4Kids - 1 year and 8 months ago
  • A Java 11 migration successful story - 2 years and 3 weeks ago
  • Tips to make your WordPress website secure - 2 years and 3 months ago
  • Devoxx UK 2018 – Day 2 - 2 years and 7 months ago
  • Devoxx UK 2018 – Day 1 - 2 years and 7 months ago
  • TransferWise, Revolut and Monzo, a small revolution for travelers and expats - 2 years and 11 months ago
  • Autocomplete for Git - 3 years and 7 months ago
  • Swagger, the automated API documentation - 3 years and 10 months ago
  • Microservices architecture – Best practices - 4 years and 3 months ago
  • FAQ – Online survey with Google Forms / Drive / Docs - 4 years and 8 months ago
  • QCon London 2016 – Project Jigsaw in JDK 9 – Modularity comes to Java - 4 years and 9 months ago
Buy me a coffee

Language

  • Français
  • English

Follow me!

Follow me on Linkedin
Follow me on Twitter
Follow me on Stackoverflow
Follow me on Github
Follow me on Rss
Link to my Contact

Email subscription

Enter your email address to receive notifications of new posts.

Tags

.net agility android bash best practices blog cache cloud computing conference continuous integration css developer devoxx docker docs drive eclipse extreme programming firefox flagger forms google helm hibernate istio java job jug kubernetes london mobile computing overview performance plugin programmer qcon script sharing society spring tool ubuntu windows wordpress

Links

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

Categories

  • Event (15)
  • Linux (3)
  • Management (7)
  • Agile programming (29)
  • Technology (44)

Archives

  • June 2020 (1)
  • May 2020 (2)
  • July 2019 (1)
  • May 2019 (1)
  • December 2018 (1)
  • October 2018 (1)
  • June 2018 (1)
  • May 2018 (1)
  • January 2018 (1)
  • May 2017 (1)
  • March 2017 (1)
  • October 2016 (1)
  • April 2016 (2)
  • March 2016 (1)
  • November 2015 (1)
  • May 2015 (1)
  • February 2015 (1)
  • December 2014 (1)
  • November 2014 (1)
  • September 2014 (2)
  • August 2014 (1)
  • July 2014 (2)
  • June 2014 (1)
  • April 2014 (1)
  • March 2014 (1)
  • February 2014 (2)
  • January 2014 (1)
  • December 2013 (1)
  • November 2013 (1)
  • October 2013 (3)
  • September 2013 (5)
  • July 2013 (1)
  • June 2013 (1)
  • May 2013 (1)
  • April 2013 (1)
  • March 2013 (2)
  • February 2013 (1)
  • January 2013 (2)
  • December 2012 (2)
  • October 2012 (1)
  • September 2012 (1)
  • July 2012 (1)
  • May 2012 (1)
  • April 2012 (1)
  • March 2012 (1)
  • February 2012 (1)
  • January 2012 (2)
  • December 2011 (1)
  • November 2011 (2)
  • October 2011 (2)
  • September 2011 (1)
  • July 2011 (1)
  • June 2011 (2)
  • April 2011 (1)
  • March 2011 (1)
  • February 2011 (1)
  • January 2011 (2)
  • November 2010 (2)
  • September 2010 (1)
  • August 2010 (1)
  • July 2010 (1)
  • June 2010 (1)
  • May 2010 (1)
  • April 2010 (1)
  • March 2010 (1)
  • February 2010 (1)
  • December 2009 (1)
  • November 2009 (1)
  • October 2009 (2)
  • September 2009 (2)
  • August 2009 (3)
  • July 2009 (1)
  • June 2009 (2)
Follow me on Twitter
Follow me on Linkedin
Follow me on Stackoverflow
Follow me on Rss
Link to my Contact
Follow me on Github
 
Fabian Piau | © 2009 - 2021
All Rights Reserved | Top ↑