Swagger, the automated API documentation
Fabian Piau | Wednesday March 1st, 2017 - 09:36 PMIT 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!”.
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)
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!
