Spring Boot 2 RESTful API Documentation with Swagger 2 Tutorial

In this article, we will discuss how to use Swagger 2 for a Spring Boot 2 RESTful API Documentation. For this article, we will use the Springfox implementation of the Swagger 2 specification.

As we know that Spring Boot makes developing RESTful services ridiculously easy — and using Swagger makes documenting your RESTful services easy.

In this article, we will create Spring boot 2 JPA CRUD RESTFul application and MySQL as a database and then we will integrate Swagger 2 for REST APIs documentation.

In order to generate the Swagger documentation, swagger-core offers a set of annotations to declare and manipulate the output. In this tutorial, we will use below set of swagger-core annotations to build a RESTFul API documentation.

A Quick Overview of Swagger-core Annotations

Name	Description
@Api	Marks a class as a Swagger resource.
@ApiModel	Provides additional information about Swagger models.
@ApiModelProperty	Adds and manipulates data of a model property.
@ApiOperation	Describes an operation or typically an HTTP method against a specific path.
@ApiParam	Adds additional meta-data for operation parameters.
@ApiResponse	Describes a possible response of an operation.
@ApiResponses	A wrapper to allow a list of multiple ApiResponse objects.

You can find more detailed about swagger annotations on https://github.com/swagger-api/swagger-core/wiki/annotations

Table of Contents

1. Tools and Technologies Used
2. Packaging Structure
3. The pom.xml File - Adding Swagger Dependencies
4. Create JPA Entity - Employee.java
5. Swagger 2 Annotations for REST Endpoints - EmployeeController.java
6. Create Spring Data Repository - EmployeeRepository.java
7. Exception(Error) Handling for RESTful Services
8. Configuring Swagger 2 in the Application
9. Swagger 2 Annotations for REST Endpoints
10. Swagger 2 Annotations for Model
11. Launching Swagger UI

1. Tools and Technologies Used

• Spring Boot - 2.0.5.RELEASE
• JDK - 1.8 or later
• Spring Framework - 5.0.8 RELEASE
• Hibernate - 5.2.17.Final
• JPA
• Maven - 3.2+
• Swagger - 2+
• springfox-swagger2 - 2.8.0
• springfox-swagger-ui - 2.8.0
• IDE - Eclipse or Spring Tool Suite (STS)

Let's create and import Spring application in your favorite IDE. There are many ways to create a Spring Boot application. The simplest way is to use Spring Initializr at http://start.spring.io/, which is an online Spring Boot application generator.

Please refer below project code structure for your reference.

2. Project Code Structure

Finally, our project code looks like this -

3. Adding Swagger Dependencies

The Swagger 2 specification, which is known as OpenAPI specification, has several implementations. Currently, Springfox that has replaced Swagger-SpringMVC (Swagger 1.2 and older) is popular for Spring Boot applications. Springfox supports both Swagger 1.2 and 2.0.

We will be using Springfox in our project. To bring it in, we need the following dependency declaration in our Maven POM.

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.8.0</version>
</dependency>

In addition to Springfox, we also require Swagger UI. The code to include Swagger UI is this.

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

The complete pom.xml file for your reference -

<?xml version="1.0" encoding="UTF-8"?>
<project
    xmlns="http://maven.apache.org/POM/4.0.0"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>net.guides.springboot2</groupId>
    <artifactId>springboot2-jpa-swagger2</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>jar</packaging>
    <name>springboot2-jpa-swagger2</name>
    <description>Demo project for Spring Boot</description>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.0.5.RELEASE</version>
        <relativePath />
        <!-- lookup parent from repository -->
    </parent>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>
        <!-- Swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-bean-validators</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>javax.xml</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.1</version>
        </dependency>
    </dependencies>
    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Let's first quickly create a CRUD Spring Boot RESTFul web services then we will integrate with swagger.

4. Create JPA Entity - Employee.java

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "employees")
public class Employee {

 private long id;
 private String firstName;
 private String lastName;
 private String emailId;
 
 public Employee() {
  
 }
 
 public Employee(String firstName, String lastName, String emailId) {
  this.firstName = firstName;
  this.lastName = lastName;
  this.emailId = emailId;
 }
 
 @Id
 @GeneratedValue(strategy = GenerationType.AUTO)
 public long getId() {
  return id;
 }
 public void setId(long id) {
  this.id = id;
 }
 
 @Column(name = "first_name", nullable = false)
 public String getFirstName() {
  return firstName;
 }
 public void setFirstName(String firstName) {
  this.firstName = firstName;
 }
 
 @Column(name = "last_name", nullable = false)
 public String getLastName() {
  return lastName;
 }
 public void setLastName(String lastName) {
  this.lastName = lastName;
 }
 
 @Column(name = "email_address", nullable = false)
 public String getEmailId() {
  return emailId;
 }
 public void setEmailId(String emailId) {
  this.emailId = emailId;
 }

 @Override
 public String toString() {
  return "Employee [id=" + id + ", firstName=" + firstName + ", lastName=" + lastName + ", emailId=" + emailId
    + "]";
 }
 
}

5. Create Spring Data Repository - EmployeeRepository.java

import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.stereotype.Repository;

import net.guides.springboot2.springboot2jpacrudexample.model.Employee;

@Repository
public interface EmployeeRepository extends JpaRepository<Employee, Long>{

}

6. Create Spring Rest Controller - EmployeeController.java

package net.guides.springboot2.springboot2jpacrudexample.controller;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import javax.validation.Valid;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import net.guides.springboot2.springboot2jpacrudexample.exception.ResourceNotFoundException;
import net.guides.springboot2.springboot2jpacrudexample.model.Employee;
import net.guides.springboot2.springboot2jpacrudexample.repository.EmployeeRepository;

@RestController
@RequestMapping("/api/v1")
public class EmployeeController {
 @Autowired
 private EmployeeRepository employeeRepository;

 @GetMapping("/employees")
 public List<Employee> getAllEmployees() {
  return employeeRepository.findAll();
 }

 @GetMapping("/employees/{id}")
 public ResponseEntity<Employee> getEmployeeById(@PathVariable(value = "id") Long employeeId)
   throws ResourceNotFoundException {
  Employee employee = employeeRepository.findById(employeeId)
    .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));
  return ResponseEntity.ok().body(employee);
 }

 @PostMapping("/employees")
 public Employee createEmployee(@Valid @RequestBody Employee employee) {
  return employeeRepository.save(employee);
 }

 @PutMapping("/employees/{id}")
 public ResponseEntity<Employee> updateEmployee(@PathVariable(value = "id") Long employeeId,
   @Valid @RequestBody Employee employeeDetails) throws ResourceNotFoundException {
  Employee employee = employeeRepository.findById(employeeId)
    .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

  employee.setEmailId(employeeDetails.getEmailId());
  employee.setLastName(employeeDetails.getLastName());
  employee.setFirstName(employeeDetails.getFirstName());
  final Employee updatedEmployee = employeeRepository.save(employee);
  return ResponseEntity.ok(updatedEmployee);
 }

 @DeleteMapping("/employees/{id}")
 public Map<String, Boolean> deleteEmployee(@PathVariable(value = "id") Long employeeId)
   throws ResourceNotFoundException {
  Employee employee = employeeRepository.findById(employeeId)
    .orElseThrow(() -> new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

  employeeRepository.delete(employee);
  Map<String, Boolean> response = new HashMap<>();
  response.put("deleted", Boolean.TRUE);
  return response;
 }
}

7. Exception(Error) Handling for RESTful Services

Spring Boot provides a good default implementation for exception handling for RESTful Services. Let’s quickly look at the default Exception Handling features provided by Spring Boot.

Resource Not Present

Heres what happens when you fire a request to not resource found: http://localhost:8080/some-dummy-url

{
  "timestamp": 1512713804164,
  "status": 404,
  "error": "Not Found",
  "message": "No message available",
  "path": "/some-dummy-url"
}

That's a cool error response. It contains all the details that are typically needed.

What happens when we throw an Exception?

Let’s see what Spring Boot does when an exception is thrown from a Resource. we can specify the Response Status for a specific exception along with the definition of the Exception of ‘@ResponseStatus’ annotation.

Lets create a ResourceNotFoundException.java class.

import org.springframework.http.HttpStatus;
import org.springframework.web.bind.annotation.ResponseStatus;

@ResponseStatus(value = HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends Exception{

 private static final long serialVersionUID = 1L;

 public ResourceNotFoundException(String message){
     super(message);
    }
}

Customizing Error Response Structure

Default error response provided by Spring Boot contains all the details that are typically needed.

However, you might want to create a framework independent response structure for your organization. In that case, you can define a specific error response structure.

Let’s define a simple error response bean.

import java.util.Date;

public class ErrorDetails {
 private Date timestamp;
 private String message;
 private String details;

 public ErrorDetails(Date timestamp, String message, String details) {
  super();
  this.timestamp = timestamp;
  this.message = message;
  this.details = details;
 }

 public Date getTimestamp() {
  return timestamp;
 }

 public String getMessage() {
  return message;
 }

 public String getDetails() {
  return details;
 }
}

To use ErrorDetails to return the error response, let’s create a GlobalExceptionHandler class annotated with @ControllerAdvice annotation. This class handles exception specific and global exception in single place.

import java.util.Date;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.context.request.WebRequest;

@ControllerAdvice
public class GlobalExceptionHandler {
 @ExceptionHandler(ResourceNotFoundException.class)
 public ResponseEntity<?> resourceNotFoundException(ResourceNotFoundException ex, WebRequest request) {
  ErrorDetails errorDetails = new ErrorDetails(new Date(), ex.getMessage(), request.getDescription(false));
  return new ResponseEntity<>(errorDetails, HttpStatus.NOT_FOUND);
 }

 @ExceptionHandler(Exception.class)
 public ResponseEntity<?> globleExcpetionHandler(Exception ex, WebRequest request) {
  ErrorDetails errorDetails = new ErrorDetails(new Date(), ex.getMessage(), request.getDescription(false));
  return new ResponseEntity<>(errorDetails, HttpStatus.INTERNAL_SERVER_ERROR);
 }
}

8. Configuring Swagger 2 in the Application

Springfox provides @EnableSwagger2 annotation which indicates that Swagger support should be enabled. This should be applied to a Spring Java config and should have an accompanying '@Configuration' annotation. 

Let's create a Docket bean in a Spring Boot configuration to configure Swagger 2 for the application. A Springfox Docket instance provides the primary API configuration with sensible defaults and convenience methods for configuration. 

Let's customizing Swagger by providing information about our API in the Swagger2Config class like this.

package net.guides.springboot2.springboot2swagger2.config;

import static springfox.documentation.builders.PathSelectors.regex;

import java.util.Collections;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2).select()
            .apis(RequestHandlerSelectors
                .basePackage("net.guides.springboot2.springboot2swagger2.controller"))
            .paths(PathSelectors.regex("/.*"))
            .build().apiInfo(apiEndPointsInfo());
    }

    private ApiInfo apiEndPointsInfo() {

        return new ApiInfoBuilder().title("Spring Boot REST API")
            .description("Employee Management REST API")
            .contact(new Contact("Ramesh Fadatare", "www.javaguides.net", "ramesh24fadatare@gmail.com"))
            .license("Apache 2.0")
            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
            .version("1.0.0")
            .build();
    }
}

In this configuration class, the @EnableSwagger2 annotation enables Swagger support in the class. The select() method called on the Docket bean instance returns an ApiSelectorBuilder, which provides the apis() and paths() methods that are used to filter the controllers and methods that are being documented using String predicates.

In the code, the RequestHandlerSelectors.basePackage predicate matches the net.guides.springboot2.springboot2swagger2.controller base package to filter the API.

In the Swagger2Config class, we have added an apiEndPointsInfo() method that returns and ApiInfo object initialized with information about our API.

Let's use http://localhost:8080/swagger-ui.html link to view swagger UI.

The Swagger 2-generated documentation now looks similar to this:

9. Swagger 2 Annotations for REST Endpoints

Let's discuss the important annotations that swagger provided to customize REST endpoints documentation.

We can use the @Api annotation on our EmployeeController class to describe our API.

@Api(value="Employee Management System", description="Operations pertaining to employee in Employee Management System")
public class EmployeeController {}

For each of our operation endpoints, we can use the @ApiOperation annotation to describe the endpoint and its response type, like this:

@ApiOperation(value = "View a list of available employees", response = List.class)
@GetMapping("/employees")
public List < Employee > getAllEmployees() {
    return employeeRepository.findAll();
}

Swagger 2 also allows overriding the default response messages of HTTP methods. You can use the @ApiResponse annotation to document other responses, in addition to the regular HTTP 200 OK, like this.

@ApiOperation(value = "View a list of available employees", response = List.class)
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "Successfully retrieved list"),
    @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
    @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
    @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
})
@GetMapping("/employees")
public List < Employee > getAllEmployees() {
    return employeeRepository.findAll();
}

We can also use @ApiParam annotation to add additional meta-data for operation parameters like this:

@ApiOperation(value = "Add an employee")
@PostMapping("/employees")
public Employee createEmployee(
    @ApiParam(value = "Employee object store in database table", required = true) @Valid @RequestBody Employee employee) {
    return employeeRepository.save(employee);
}

The complete EmployeeController code with swagger annotations:

package net.guides.springboot2.springboot2swagger2.controller;

import java.util.HashMap;
import java.util.List;
import java.util.Map;

import javax.validation.Valid;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import net.guides.springboot2.springboot2swagger2.exception.ResourceNotFoundException;
import net.guides.springboot2.springboot2swagger2.model.Employee;
import net.guides.springboot2.springboot2swagger2.repository.EmployeeRepository;

@RestController
@RequestMapping("/api/v1")
@Api(value = "Employee Management System", description = "Operations pertaining to employee in Employee Management System")
public class EmployeeController {
    @Autowired
    private EmployeeRepository employeeRepository;

    @ApiOperation(value = "View a list of available employees", response = List.class)
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "Successfully retrieved list"),
        @ApiResponse(code = 401, message = "You are not authorized to view the resource"),
        @ApiResponse(code = 403, message = "Accessing the resource you were trying to reach is forbidden"),
        @ApiResponse(code = 404, message = "The resource you were trying to reach is not found")
    })
    @GetMapping("/employees")
    public List < Employee > getAllEmployees() {
        return employeeRepository.findAll();
    }

    @ApiOperation(value = "Get an employee by Id")
    @GetMapping("/employees/{id}")
    public ResponseEntity < Employee > getEmployeeById(
        @ApiParam(value = "Employee id from which employee object will retrieve", required = true) @PathVariable(value = "id") Long employeeId)
    throws ResourceNotFoundException {
        Employee employee = employeeRepository.findById(employeeId)
            .orElseThrow(() - > new ResourceNotFoundException("Employee not found for this id :: " + employeeId));
        return ResponseEntity.ok().body(employee);
    }

    @ApiOperation(value = "Add an employee")
    @PostMapping("/employees")
    public Employee createEmployee(
        @ApiParam(value = "Employee object store in database table", required = true) @Valid @RequestBody Employee employee) {
        return employeeRepository.save(employee);
    }

    @ApiOperation(value = "Update an employee")
    @PutMapping("/employees/{id}")
    public ResponseEntity < Employee > updateEmployee(
        @ApiParam(value = "Employee Id to update employee object", required = true) @PathVariable(value = "id") Long employeeId,
        @ApiParam(value = "Update employee object", required = true) @Valid @RequestBody Employee employeeDetails) throws ResourceNotFoundException {
        Employee employee = employeeRepository.findById(employeeId)
            .orElseThrow(() - > new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

        employee.setEmailId(employeeDetails.getEmailId());
        employee.setLastName(employeeDetails.getLastName());
        employee.setFirstName(employeeDetails.getFirstName());
        final Employee updatedEmployee = employeeRepository.save(employee);
        return ResponseEntity.ok(updatedEmployee);
    }

    @ApiOperation(value = "Delete an employee")
    @DeleteMapping("/employees/{id}")
    public Map < String, Boolean > deleteEmployee(
        @ApiParam(value = "Employee Id from which employee object will delete from database table", required = true) @PathVariable(value = "id") Long employeeId)
    throws ResourceNotFoundException {
        Employee employee = employeeRepository.findById(employeeId)
            .orElseThrow(() - > new ResourceNotFoundException("Employee not found for this id :: " + employeeId));

        employeeRepository.delete(employee);
        Map < String, Boolean > response = new HashMap < > ();
        response.put("deleted", Boolean.TRUE);
        return response;
    }
}

The output of the operation endpoints on the browser is this:

The current documentation is missing one thing: documentation of the Employee JPA entity. We will generate documentation for our model in the next step.

10. Swagger 2 Annotations for Model

You can use the @ApiModelProperty annotation to describe the properties of the Employee model. With @ApiModelProperty, we can also document a property as required.

The code of our Employee class is this.

package net.guides.springboot2.springboot2swagger2.model;

import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@Entity
@Table(name = "employees")
@ApiModel(description = "All details about the Employee. ")
public class Employee {

    @ApiModelProperty(notes = "The database generated employee ID")
    private long id;

    @ApiModelProperty(notes = "The employee first name")
    private String firstName;

    @ApiModelProperty(notes = "The employee last name")
    private String lastName;

    @ApiModelProperty(notes = "The employee email id")
    private String emailId;

    public Employee() {

    }

    public Employee(String firstName, String lastName, String emailId) {
        this.firstName = firstName;
        this.lastName = lastName;
        this.emailId = emailId;
    }

    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    public long getId() {
        return id;
    }

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

    @Column(name = "first_name", nullable = false)
    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }

    @Column(name = "last_name", nullable = false)
    public String getLastName() {
        return lastName;
    }

    public void setLastName(String lastName) {
        this.lastName = lastName;
    }

    @Column(name = "email_address", nullable = false)
    public String getEmailId() {
        return emailId;
    }

    public void setEmailId(String emailId) {
        this.emailId = emailId;
    }

    @Override
    public String toString() {
        return "Employee [id=" + id + ", firstName=" + firstName + ", lastName=" + lastName + ", emailId=" + emailId +
            "]";
    }
}

The Swagger 2 generated documentation for Employee is this:

11. Launching Swagger UI

Let's use the Swagger UI available at http://localhost:8080/swagger-ui.html.

Below screenshot shows the Home Page of Swagger UI. It shows a list of all the resources that are exposed.

Expand employee-controller and Models looks as below screenshots:

Expand each REST API and you can use the ‘Try it out’ button to execute a request and see the response. Below are a demo of getting all employees and delete employee looks like this:

Check out the source code of this tutorial on GitHub - https://github.com/RameshMF/spring-boot-tutorial/tree/master/springboot2-jpa-swagger2

Master Spring Boot on Spring Boot Tutorial (Top viewed)