In this post lets explore on how to automatically generate Swagger Rest API documentation for Spring Boot Applications using Springfox library.
More than any application, up to-date documentation is necessary for Rest APIs and especially in the Microservice architecture as the APIs are consumed by different clients and also composed into applications of varied nature.
Maintaining API documentations can prove to be cumbersome activity and eventually focus can be lost. As APIs evolve, this can lead unseen issues and failures at multiple points.
Swagger with the OpenAPI specification provides numerous tools for design, development and documentation of APIs
Springfox library provides one of the implementations for automatic creation of Swagger documentations for the APIs in a fairly simple way.
Let’s explore on how to achieve this with a simple example on Spring Boot Application.
- Initialise a simple Spring Boot Application with Spring Web dependency using the Spring Initializr application.
- Add the Springfox library dependencies to the POM definition.
The Springfox library automatically scans all the API resources defined in the application via @Controller components and adds them to the “documentation index”.
- Let’s define a sample Controller with API endpoints defined.
Yes, just adding the library to the application, takes care of all other ground work and it’s almost done..
- Start the application and hit the api-docs URI.. boom.. http://localhost:8080/swagger-ui/
We get a nice and clean Swagger API documentation with the available resources in the application. Explore them..!!
API meta-data and config information can be added to the documentation by defining a Configuration component with @EnableSwagger2WebMvc Annotation.
Details like Contact, Terms of Service, license, common default configs and much more can be configured here.
A clear API documentation can help in a long way to achieve better results and less chaos 😉
Please refer the following repo for the complete sample code https://github.com/muralidharan-rade/swagger-sample