Create Swagger 2 API documentation for REST

For one of our clients we developed micro REST web services using Spring Boot. Micro web services is a developing trend in industry. You design your component and expose the functions as a web services (just like Service oriented architecture). These components are small, independent and represent a small function . These services can be consumed by applications within the same server or over the network. This gives more flexibility and reduces the tight coupling that we find in many earlier applications.

There are several hundreds of endpoints. Documenting those endpoints and keeping them up to date with new changes is a big task. A small mismatch between the actual implementation and documentation is a cause for problems and confusion.

To fix this, we decided to use SWAGGER 2 for automatic documentation of the REST endpoints. With minimal configurations and without any complexities SWAGGER provides the documentation.

Here are the code snippets for how we managed this in our project.

1. Add the swagger dependencies to the pom.xml
2. Register the below beans in your Spring Configuration file
   1. Enable swagger2 by adding @EnableSwagger2 annotation
   2. Register swagger 2 related beans
3. Annotate your model classes 
4. Annotate your controllers

And you are ready with your documentation.

If you have any questions about this blogpost contact us via the comments section of this blog. View also our WSO2 Tutorials, webinars or white papers for more technical information. Need support? We do deliver WSO2 Product Support, WSO2 Development Support, WSO2 Operational Support and WSO2 Training Programs.