Boot the Swagger: API as good as it's documentation.


Swagger provides one of the best representation of the REST API during development. It provides interactive API documentation baked in with the application itself. Contrary to create separate specification document with cost of maintenance and risk of obsolete, Swagger generates the API documentation on the run time with updates. It also provides user friendly REST interface to test the code at the same place. This idea of live documentation has real value, and I guess you should give a try during API development.

In one of the recent engagement, I had to showcase the working proto of Swagger to the client, and being said easy to setup I estimated it for 15 mins. But I was damn wrong, I had to spend 2 hours to get Swagger up and running. So, I had an idea why not to just simplify the Swagger configuration process in very simple steps, so hungry user like me can configure in existing application and see the benefits.

I configured it for Spring Boot, but I fairly assume it should be similar in most Swagger supported frameworks.

Add dependency.

In pom.xml

Add Configuration Class

Add annotations.

For every REST endpoint methods of Controller, @ApiOperation annotation needs to be added. For eg,

Add Swagger UI HTML library from GitHub.

Download Swagger UI Library v2.1.1 from Github into resource/public folder. Replace the declaration of Url from the first index.html function,

These are minimal steps required to spinup swagger on existing Spring Boot web application. Swagger API configuration and Swagger UI documentation can be seen at

http://localhost:8080/api-docs

http://localhost:8080/index.html

Note

Swagger has been updated with Specification 2.0. Version used in the example may go obsolete in near by future.