API documentation – Swagger

Posted in Documentation on December 24th, 2013 by Abhishek Balaria – Comments Off

For many, one of the principles of agile is delivering working software over comprehensive documentation. Software developers often see it as a pain to create the documentation. But the documentation is a must and required by managers, customers, collaborators, etc. so it is important to find approaches and tools which can help us document our products.

Swagger is a specification and framework to document REST APIs. I tried Spring-MVC integration. The result was amazing and worth sharing.

Swagger MVC scans in given package path for Spring MVC annotations and turns it into Swagger API specification. It tries to extract API resources from @Controller classes and API calls names, HTTP methods, request and response type from @RequestMapping methods and so one.

It also supports @ApiOperation and @Api annotations, but @Api was not working for me from some reason.

API specification can be rendered as xml or json.

Swagger UI uses json API specification to build nice looking visual documentation which contains also prepared REST client for each call.

To set up your Spring MVC project together with Swagger just add Maven dependencies and follow simple instructions which you can find on project site.

I had only three problems during using Swagger. @Api annotation was not working for me, extensibility module is poorly documented and I didn’t get it working and Swagger is not following Jackson custom serializers and deserializers.

I tried also JSONDoc but it doesn’t use Spring MVC or JAX-RS annotations to build your documentation and you have to write your documentation through jsondoc annotations which is not so productive, especially when your API is changing during early development and you need to provide documentation to collaborates.