Spring Boot – REST API Documentation using Swagger

REST stands for Representational State Transfer. REST is an architectural design pattern that defines constraints that are used in web service development. Swagger is a framework in which we can test our REST APIs for different HTTP requests i.e. :

• GET
• POST
• PUT
• DELETE

In this article, we will be discussing using Swagger for documenting APIs in Spring Boot applications.

What is Swagger?

Swagger is an open-source API Documentation framework used for documenting the rest APIs. it provides the HTML view of the API documentation with JSON support and detailed information on the HTTP methods. REST APIs are designed to be used in some kinds of applications.

Steps to use Swagger for documenting APIs

There are two Main Steps to use Swagger for Documenting APIS these are Project Setup and then Setting up Swagger.

Project Setup

Step 1: Maven Project

• Go to https://start.spring.io/ and create a Maven project with the latest version of Spring Boot.
• Add the Web dependencies to the project.
• Download the project.

• Extract the project and open with VS Code (Or any IDE you prefer), you can see a similar project structure (as shown below).

• Now, open a terminal and run using the below command:

      mvn install

• To install the dependency and then run follow the below command:

      mvn spring-boot:run

Now start the spring boot project,

Step 2: Gradle Project

• Go to https://start.spring.io/ and create a Gradle project with the latest version of Spring Boot.
• Add the Web dependencies to the project.
• Download the project.

• Extract the project and open with VS Code (Or any IDE you prefer), you can see a similar project structure (as shown below)

• Now, open a terminal and run,

      ./gradlew build

• Then, run using the below command:

      ./gradlew bootrun 

Start the Spring project,

Step 3: Create a Rest Controller

Now let’s create a controller class which handles the HTTP request and return a response.

• Create a controller class(model class) that will be sent as a JSON response.

Java

package xyz.bijit.swagger;

public class Tweet {
    private Integer id;

    private String title;

    private String msg;

    public Integer getId() {
        return id;
    }

    public void setId(Integer id) {
        this.id = id;
    }

    public String getTitle() {
        return title;
    }

    public void setTitle(String title) {
        this.title = title;
    }

    public String getMsg() {
        return msg;
    }

    public void setMsg(String msg) {
        this.msg = msg;
    }
}

• Now create a service class to perform addTweet and getTweet,

Java

package xyz.bijit.swagger;

import org.springframework.stereotype.Service;
import java.util.ArrayList;
import java.util.List;

@Service
public class TweetService {
    private List<Tweet> tweetList = new ArrayList<>();

    public void addTweet(){
        Tweet tweet = new Tweet();
        tweet.setId(1);
        tweet.setTitle("My first tweet");
        tweet.setMsg("This is a dummy tweet for demonstration purposes.");
        tweetList.add(tweet);

        Tweet tweet2 = new Tweet();
        tweet2.setId(2);
        tweet2.setTitle("My second tweet");
        tweet2.setMsg("This is the second dummy tweet for demonstration purposes.");
        tweetList.add(tweet2);
    }

    public List<Tweet> getTweets() {
        return tweetList;
    }


}

• Now create the RestController Class.

Java

package xyz.bijit.swagger;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;
import java.util.List;

@RestController
public class TweetController {
    @Autowired
    private TweetService tweetService;

    @PostMapping("/add")
    public void addTweet() {
        tweetService.addTweet();
    }

    @GetMapping("/view")
    public List<Tweet> viewTweets() {
        return tweetService.getTweets();
    }

    @GetMapping("/hello")
    public String hello(){
        return "Hello World!";
    }
}

The @RestController annotation marks a class as a REST controller, which is responsible for handling HTTP requests and generating responses in a RESTful manner. Now make a post request using curl.

curl --request POST \
  --url http://localhost:8080/add

• Go to the URL http://localhost:8080/view.

Setting up Swagger

Step 1: Adding Maven Dependency

To enable the Swagger in Spring Boot application with maven dependency, add the following dependencies in build configuration (pom.xml) file.

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
</dependency>
<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
</dependency>

Run the below command in terminal to install the dependencies:

mvn clean install

Step 2: Adding Gradle Dependency

To install the Swagger in Spring Boot application with gradle dependency, add the following dependencies in build configuration (build.gradle) file.

dependencies {
    implementation 'io.springfox:springfox-swagger2:2.7.0'
    implementation 'io.springfox:springfox-swagger-ui:2.7.0'
}

Run the below command to install the dependencies and build the project:

./gradlew clean build

Step 3: Configure Main Class

Enable main application file to use Swagger.

@EnableSwagger2 is used for it and after enabling it, main application file should like as follows:

Java

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
@EnableWebMvc
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

Step 4: Configure Swagger

Java

import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

   public Docket SwaggerApi() {
       return new Docket(DocumentationType.SWAGGER_2)
               .select()
               .apis(RequestHandlerSelectors.any())
               .paths(PathSelectors.any())
               .build();
   }

Output:

• Documentation is available at the following url for json format: http://server:port/v2/api-docs
  • server: The server name or IP
  • port: The server port

• Documentation is available at the following url with UI: http://server:port/swagger-ui/index.html/

Note: If you are using spring security make sure to Whitelist the above url

Accessing Swagger UI

Now navigate to http://server:port/swagger-ui/index.html/.