Swagger, the automated API documentation

Home Agile programming Swagger, the automated API documentation

Swagger, the automated API documentation

Fabian Piau | Wednesday March 1st, 2017 - 09:36 PM

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!”.

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!

Categories: Agile programming
Tags: best practices, microservices, tool, spring
: Comments rss

Anthony Defraine
Hi Fab,
Hope your doing good since last time we worked together at Lampiris =)
I have been using Swagger for one and half year in production and it improved everything (communication with other team, nice entry point for some business analyst to test, …).
But I don’t like the fact you need to add shit in your code to be able to configure your swagger entry point. Maybe I missed something. Do you know anything about that ?
Cheers;
Anthony
- Fabian Piau
  Hey Anthony!
  Obviously I remember you 😉
  Yes, you are right, Swagger can be quite intrusive in the code, and there is no magical solution for that. At least you limit the annotations to the exposed methods of the API, the request & response objects.
  What I did to avoid too much text, I created a bean SwaggerDocumentation with all the texts and business messages. So it does not pollute the code itself, and address duplication for common text, e.g. a same parameter with same description/name/etc used for different endpoints .
  I end up with a code like this:
```
@RequestMapping(method = RequestMethod.GET)
@ApiOperation(value = SwaggerDocumentation.MyMethod.Get.DESCRIPTION, notes = SwaggerDocumentation.MyMethod.Get.NOTE, [..])
public Response myMethod([..]) {
[..]
}
```
```
@ApiParam(value = SwaggerDocumentation.Parameter.MY_PARAMETER_DESCRIPTION, required = true)
@RequestParam String myParameter
```

CarmaBlog