When creating a REST API, good documentation is instrumental.
But developers do not have any option using JSR-339 to generate any documentation on all these APIs so other developers could quickly understand how to use them. For sure, it would be just awesome to generate verbose and easy to follow documentation from source code, and but the help is coming in a form of Swagger.
Essentially, Swagger does a simple but very powerful thing: with a bit of additional annotations it generates the REST API descriptions such as HTTP methods, path / query / form parameters, responses, HTTP error codes etc) and even provides a simple web UI to play with REST calls to your APIs. Read More