Including Swagger in you Spring Boot project

 Including Swagger in you Spring Boot project

 We all would have come across APIs  which are communicating interfaces between two systems. Two famous API formats are

• SOAP (Simple Object Access Protocol) based APIs have WSDL (Web Services Description Language) format which is an XML based language for describing Web Services.

• REST (Representational State Transfer) architecture based APIs or so called RESTful web services by default do not have any description language. It is quite cumbersome for the developers to create and maintain API documentation for these. It becomes even more difficult and engaging when API specs  changes frequently or over time.

 

That’s where Swagger comes to our rescue. Today we are going to see how to include Swagger into our Spring Boot project and get the REST API documentation with Swagger UI.

 We will start from scratch.

Step 1: Generate simple Spring Boot project with Spring initializer

From https://start.spring.io/ use below setting to generate a project. We have added Spring Web dependency to enable RESTful API development.

Click generate to download project zip file.

 

Step 2:

Extract zip and import the project into IDE of your choice. Since we have selected Maven. After import run Maven update on the project to update the Maven dependencies.

 

Step 3: 

For demo we need to add two classes UserInfo.java (Resource domin class) and UserInfoResource.java which is our Rest Controller. (Source code is attached at the end of the page.)

The Controller resource file exposes endpoints as below:

Step 4:

I will add 3 simple REST API endpoints for demo purpose.

Run the project as Spring Boot Application by selecting its main class.

 

Test the API endpoints using postman tool.

 Insert data wih POST enpoint, make content-type as application/json under headers tab.

So the data will b in our array list, we can check the same with out GET API endpoint.

So far so good!, our test APIs are ready.

 

 Step 5:

So now lets add Swagger dependencies to our project. Here we are going to add Springfox implementation of Swagger specification. Add below code to project’s pom.xml file and update project wih Maven -> Update Proejct (Alt + F5)

 

<dependency>

    <groupId>io.springfox</groupId>

    <artifactId>springfox-boot-starter</artifactId>

    <version>3.0.0</version>

</dependency>

 

Run the project and we are set.

 

We will get two type of documentations here:

 

JSON Based:

 

Hit URL : http://localhost:8080/v2/api-docs in browser or Postmn to get the JSON documentation for your APIs.

To get the Swagger-UI based documentation, visit URL http://localhost:8080/swagger-ui in browser. You documentation will be auto generated by Swagger in a well formatted way.

You can click on API end points, view further details and also try out the APIs with sample data (Just like postman)

So, we explored Swagger today, which is a powerful tool for API documentation and is used in industry.

Source code can be downloaded from : 

source code 🍻

Let me know your feedback in comments.