Springfox Swagger 2 for Spring RESTful Web Services

In this tutorial, we will look at Swagger 2 for Spring RESTful web services. Swagger is a specification for documenting REST API.It provides tools to generate documentation from our REST code. Swagger scans the code and exposes the documentation of the URLs, any clients which consume our REST Web services knows which HTTP method call on which URL, which input send, what will be the status code that will be returned etc.

Swagger specification also know as “OpenAPI specification“ has many implementation, Springfox Integrated swagger with Spring MVC with support for Swagger 1.2 and Swagger 2.0 specifications. In order to use springfox in our project we will have to add the below dependency

 <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
 </dependency>

 <dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.6.1</version>
    <scope>compile</scope>
 </dependency>

Spring RESTful Web Services

As a first step, Lets quickly create our REST endpoints for our Employee management system.

Creating table

Create EMPLOYEE Table, simply Copy and Paste the following SQL query in the query editor to get the table created.

CREATE TABLE EMPLOYEE
 (
    ID INT(10) NOT NULL, 
    NAME VARCHAR(255), 
    DEPT VARCHAR(255), 
    AGE INT(10), 
    PRIMARY KEY(ID)
 );

Folder Structure:

Create a simple Maven Project “SpringRestSwagger” by selecting maven-archetype-webapp and create a package for our source files “com.javainterviewpoint” under src/main/java

Now add the following dependency in the POM.xml

<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/maven-v4_0_0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<groupId>com.javainterviewpoint</groupId>
	<artifactId>SpringRestSwagger</artifactId>
	<packaging>war</packaging>
	<version>0.0.1-SNAPSHOT</version>
	<name>SpringRestSwagger Maven Webapp</name>
	<url>http://maven.apache.org</url>
	<properties>
		<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
		<springframework.version>4.3.7.RELEASE</springframework.version>
		<hibernate.version>4.3.11.Final</hibernate.version>
		<oracle.connector.version>11.2.0</oracle.connector.version>
		<jstl.version>1.2</jstl.version>
	</properties>

	<dependencies>

		<dependency>
			<groupId>junit</groupId>
			<artifactId>junit</artifactId>
			<version>3.8.1</version>
			<scope>test</scope>
		</dependency>

		<!-- Spring mvc 4 dependencies -->
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-core</artifactId>
			<version>${springframework.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-context</artifactId>
			<version>${springframework.version}</version>
		</dependency>
		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-web</artifactId>
			<version>${springframework.version}</version>
		</dependency>

		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-webmvc</artifactId>
			<version>${springframework.version}</version>
		</dependency>

		<dependency>
			<groupId>org.springframework</groupId>
			<artifactId>spring-jdbc</artifactId>
			<version>${springframework.version}</version>
		</dependency>
		<!-- Swagger 2 -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger2</artifactId>
			<version>2.6.1</version>
			<scope>compile</scope>
		</dependency>

		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-swagger-ui</artifactId>
			<version>2.6.1</version>
			<scope>compile</scope>
		</dependency>

		<!-- jstl for jsp page -->
		<dependency>
			<groupId>jstl</groupId>
			<artifactId>jstl</artifactId>
			<version>${jstl.version}</version>
		</dependency>
		<dependency>
			<groupId>javax.servlet</groupId>
			<artifactId>javax.servlet-api</artifactId>
			<version>3.1.0</version>
			<scope>provided</scope>
		</dependency>
		<dependency>
			<groupId>javax.servlet.jsp</groupId>
			<artifactId>javax.servlet.jsp-api</artifactId>
			<version>2.3.1</version>
			<scope>provided</scope>
		</dependency>

		<dependency>
			<groupId>com.fasterxml.jackson.core</groupId>
			<artifactId>jackson-databind</artifactId>
			<version>2.8.1</version>
		</dependency>

		<!-- Oracle -->
		<dependency>
			<groupId>com.oracle</groupId>
			<artifactId>ojdbc14</artifactId>
			<version>${oracle.connector.version}</version>
		</dependency>
	</dependencies>
	<build>
		<finalName>SpringRestSwagger</finalName>
		<plugins>
			<plugin>
				<artifactId>maven-compiler-plugin</artifactId>
				<configuration>
					<source>1.7</source>
					<target>1.7</target>
				</configuration>
				<version>3.0</version>
			</plugin>
		</plugins>
	</build>
</project>

Create the Java classes Employee.java, EmployeeController.java, EmployeeDAO.java and EmployeeDAOImpl.java under com.javainterviewpoint folder.
Place the employees.jsp under /WEB-INF/JSP directory.
Place the web.xml and SpringMVC-servlet.xml under the /WEB-INF directory

EmployeeDAO.java

package com.javainterviewpoint;

import java.util.List;
public interface EmployeeDAO
{
    public void saveEmployee(Employee employee);
    public Employee getEmployeeById(Long id);
    public void updateEmployee(Employee employee);
    public void deleteEmployee(Long id);
    public List getAllEmployees();
}

EmployeeDAOImpl.java

package com.javainterviewpoint;

import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.List;

import org.springframework.dao.DataAccessException;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.core.ResultSetExtractor;
import org.springframework.jdbc.core.RowMapper;
import org.springframework.stereotype.Repository;

@Repository
public class EmployeeDAOImpl implements EmployeeDAO
{

    private JdbcTemplate jdbcTemplate;
    // JdbcTemplate setter
    public void setJdbcTemplate(JdbcTemplate jdbcTemplate)
    {
        this.jdbcTemplate = jdbcTemplate;
    }

    // Saving a new Employee
    public void saveEmployee(Employee employee)
    {
        String sql = "insert into Employee values(?,?,?,?)";
        jdbcTemplate.update(sql, new Object[]
        { employee.getId(), employee.getName(),employee.getAge(), employee.getDept() });
    }

    // Getting a particular Employee
    public Employee getEmployeeById(Long id)
    {
        String sql = "select * from Employee where id=?";
        Employee employee = (Employee) jdbcTemplate.queryForObject(sql, new Object[]
        { id }, new RowMapper()
        {
            @Override
            public Employee mapRow(ResultSet rs, int rowNum) throws SQLException 
            {
                Employee employee = new Employee();
                employee.setId(rs.getLong(1));
                employee.setName(rs.getString(2));
                employee.setAge(rs.getLong(3));
                employee.setDept(rs.getString(4));
                return employee;
            }
        });
        return employee;
    }

    // Getting all the Employees
    public List getAllEmployees()
    {
        String sql = "select * from Employee";
        List employeeList = jdbcTemplate.query(sql, new ResultSetExtractor<List>()
        {
            @Override
            public List extractData(ResultSet rs) throws SQLException, DataAccessException
            {
                List list = new ArrayList();
                while (rs.next())
                {
                    Employee employee = new Employee();
                    employee.setId(rs.getLong(1));
                    employee.setName(rs.getString(2));
                    employee.setAge(rs.getLong(3));
                    employee.setDept(rs.getString(4));
                    list.add(employee);
                }
                return list;
            }

        });
        return employeeList;
    }

    // Updating a particular Employee
    public void updateEmployee(Employee employee)
    {
        String sql = "update Employee set age =?, dept=?,name=? where id=?";
        jdbcTemplate.update(sql, new Object[]
        { employee.getAge(), employee.getDept(), employee.getName(), employee.getId() });
    }

    // Deletion of a particular Employee
    public void deleteEmployee(Long id)
    {
        String sql = "delete employee where id=?";
        jdbcTemplate.update(sql, new Object[]
        { id });
    }
}

EmployeeController.java

package com.javainterviewpoint;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping(value="/api")
public class EmployeeController
{
    @Autowired
    private EmployeeDAOImpl employeeDAO;

    @RequestMapping(value = "/create",method=RequestMethod.POST)
    public void saveEmployee(@RequestBody Employee employee)
    {
        employeeDAO.saveEmployee(employee);
    }
    
    @RequestMapping(value = "/employee/{id}",method=RequestMethod.GET)
    public Employee getEmployeeById(@PathVariable("id") Long id)
    {
        
        Employee employee = employeeDAO.getEmployeeById(id);
        return employee;
        
    }
    
    @RequestMapping(value = "/employees",method=RequestMethod.GET)
    public List listEmployees()
    {
        List employeeList = employeeDAO.getAllEmployees();
        return employeeList;
    }
    
    @RequestMapping(value = "/update",method=RequestMethod.PUT)
    public void update(@RequestBody Employee employee)
    {
        employeeDAO.updateEmployee(employee);
    }
    
    @RequestMapping(value = "/delete/{id}",method=RequestMethod.DELETE)
    public void deleteEmployee(@PathVariable("id") Long id)
    {
        employeeDAO.deleteEmployee(id);
    }
}

Employee.java

Our Employee class is a simple POJO class consisting getters and setters of Employee properties id, name, age, dept.

package com.javainterviewpoint;

import java.io.Serializable;

public class Employee implements Serializable 
{
    private static final long serialVersionUID = -889976693182180703L;
    
    private Long id;
    private String name;
    private Long age;
    private String dept;
    public Employee()
    {
        super();
    }
    public Employee(Long id, String name, Long age, String dept)
    {
        super();
        this.id = id;
        this.name = name;
        this.age = age;
        this.dept = dept;
    }
    public Long getId()
    {
        return id;
    }
    public void setId(Long id)
    {
        this.id = id;
    }
    public String getName()
    {
        return name;
    }
    public void setName(String name)
    {
        this.name = name;
    }
    public Long getAge()
    {
        return age;
    }
    public void setAge(Long age)
    {
        this.age = age;
    }
    public String getDept()
    {
        return dept;
    }
    public void setDept(String dept)
    {
        this.dept = dept;
    }
    @Override
    public String toString()
    {
        return "Employee [id=" + id + ", name=" + name + ", age=" + age + ", dept=" + dept + "]";
    }
}

web.xml

<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"  
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee	http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"	version="3.0">  
	<display-name>Spring Boot RESTful Web Services With Swagger 2</display-name>
	<servlet>
		<servlet-name>SpringRestSwagger</servlet-name>
		<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
	</servlet>
	<servlet-mapping>
		<servlet-name>SpringRestSwagger</servlet-name>
		<url-pattern>/</url-pattern>
	</servlet-mapping>
</web-app>

SpringConfig.xml

In our configuration file, we have defined the below beans

DriverManagerDataSource – DriverManagerDataSource contains database related configurations such as driver class name, connection URL, username and password.
JdbcTemplate – We will be referencing the dataSource id (DriverManagerDataSource ) to the property dataSource of the JdbcTemplate class.
EmployeeDAOImpl – We will be referencing the jdbcTemplate id to the property jdbcTemplate of the EmployeeDAOImpl class.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:aop="http://www.springframework.org/schema/aop"
 xmlns:tx="http://www.springframework.org/schema/tx"
 xsi:schemaLocation="http://www.springframework.org/schema/beans	http://www.springframework.org/schema/beans/spring-beans.xsd
 http://www.springframework.org/schema/aop	http://www.springframework.org/schema/aop/spring-aop-4.0.xsd
 http://www.springframework.org/schema/tx	http://www.springframework.org/schema/tx/spring-tx-4.0.xsd">

    <bean id="employeeDAOImpl" class="com.javainterviewpoint.EmployeeDAOImpl">
       <property name="jdbcTemplate" ref="jdbcTemplate" />
    </bean>

    <!-- Database Configurations -->
    <bean id="dataSource"
        class="org.springframework.jdbc.datasource.DriverManagerDataSource">
        <property name="driverClassName" value="oracle.jdbc.driver.OracleDriver" />
        <property name="url" value="jdbc:oracle:thin:@rsh2:40051:dev" />
        <property name="username" value="root" />
        <property name="password" value="root" />
     </bean>

     <bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate">
         <property name="dataSource" ref="dataSource"/>
     </bean>
     <bean id="viewResolver"
         class="org.springframework.web.servlet.view.InternalResourceViewResolver">
         <property name="prefix" value="/WEB-INF/Jsp/" />
         <property name="suffix" value=".jsp" />
     </bean>
 </beans>

Configuration without Spring Boot

Since we not using Spring Boot in our application, then we have to manually add the ResourceHandlers by yourself.

package com.javainterviewpoint;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override 
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

Configuring Swagger 2 for Spring REST

package com.javainterviewpoint;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.javainterviewpoint"))
            .paths(PathSelectors.regex("/api/.*"))
            .build();
        }
}

We can enable Swagger 2 support by using @EnableSwagger2 annotation in our configuration class.
Once after the Docket bean is defined, call the select() method over the Docket bean instance which returns the ApiSelectorBuilder instance.
ApiSelectorBuilder provides the way of controlling the endpoints exposed by swagger [ apis() , paths() ].
- apis() -> RequestHandlerSelectors.basePackage scans for the api inside the package “com.javainterviewpoint”.
- paths() -> This method act as an additional filter to generate documentation for the api with path “/api/”

Now we can validate whether we have configured Springfox Swagger 2 correclty by hitting the url “http://localhost:8080/SpringRestSwagger/v2/api-docs”

The above result is a JSON response of our Endpoints, which is not in a human readable form. Here SwaggerUI comes to the rescue. Now hit on the URL ”

“http://localhost:8080/SpringRestSwagger/swagger-ui.html”

Adding Custom Information in Swagger

Let’s customize Swagger adding our own API information, In our custInfo() method, we have created ApiInfo class instance and set the custom information about our API.

package com.javainterviewpoint;

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

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 SwaggerConfig {

    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.javainterviewpoint"))
            .paths(PathSelectors.regex("/api/.*"))
            .build()
            .apiInfo(custInfo());
    }
    public ApiInfo custInfo()
    {
       ApiInfo apiInfo = new ApiInfo(
               "Employee Managememnt",  // Title
               "Employee Service",      // Description 
               "1.0",                   // Version
               "TOS",                   // Terms of Service
               new Contact("JavaInterviewPoint", "//javainterviewpoint.com/spring-mvc-tutorial/", "[email protected]"), // Contact
               "JIPlicense",            // License
               "//javainterviewpoint.com/"); //License URL
       
        return apiInfo;
    }
}

Swagger 2 Annotations for REST Endpoints

package com.javainterviewpoint;

import java.util.List;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

@RestController
@RequestMapping(value="/api")
@Api(value="Employee Service")
public class EmployeeController
{
    @Autowired
    private EmployeeDAOImpl employeeDAO;

    @RequestMapping(value = "/create",method=RequestMethod.POST)
    @ApiOperation(value="Create Employee",notes="Creation of a new Employee",response=EmployeeController.class)
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Employee Created successfully"),
            @ApiResponse(code = 401, message = "You are Not authorized to create Employee"),
            @ApiResponse(code = 403, message = "Create Employee is forbidden"),
            @ApiResponse(code = 404, message = "Resource Not found")
    })
    public void saveEmployee(@RequestBody Employee employee)
    {
        employeeDAO.saveEmployee(employee);
    }
    
    @RequestMapping(value = "/employee/{id}",method=RequestMethod.GET)
    @ApiOperation(value="Get Employee",notes="Get Employee by a particular id",response=EmployeeController.class)
    public Employee getEmployeeById(@PathVariable("id") Long id)
    {
        
        Employee employee = employeeDAO.getEmployeeById(id);
        return employee;
        
    }
    
    @RequestMapping(value = "/employees",method=RequestMethod.GET)
    @ApiOperation(value="List of Employees",notes="Get list of all Employees",response=EmployeeController.class)
    public List listEmployees()
    {
        List employeeList = employeeDAO.getAllEmployees();
        return employeeList;
    }
    
    @RequestMapping(value = "/update",method=RequestMethod.PUT)
    @ApiOperation(value="Update Employee",notes="Update a particular Employee",response=EmployeeController.class)
    public void update(@RequestBody Employee employee)
    {
        employeeDAO.updateEmployee(employee);
    }
    
    @RequestMapping(value = "/delete/{id}",method=RequestMethod.DELETE)
    @ApiOperation(value="Delete Employee",notes="Delete a particular Employee",response=EmployeeController.class)
    public void deleteEmployee(@PathVariable("id") Long id)
    {
        employeeDAO.deleteEmployee(id);
    }
}

@Api annotation : Rest Controller (EmployeeController) class can be defined with @Api annotation
@ApiOperation : Our endpoints can be annotated with @ApiOperation annotation, it can be used to describe endpoints, response etc.

 @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Employee Created successfully"),
            @ApiResponse(code = 401, message = "You are Not authorized to create Employee"),
            @ApiResponse(code = 403, message = "Create Employee is forbidden"),
            @ApiResponse(code = 404, message = "Resource Not found")
    })

@ApiResponse : This annotation used to define custom message for the different response code.

Swagger 2 Annotations for Model

@ApiModelProperty annotation can be used to describe each property of the Model

package com.javainterviewpoint;

import java.io.Serializable;

import io.swagger.annotations.ApiModelProperty;

public class Employee implements Serializable 
{
    private static final long serialVersionUID = -889976693182180703L;
    @ApiModelProperty(value="Id of the Employee (primary key field)")
    private Long id;
    @ApiModelProperty(value="Name of the Employee")
    private String name;
    @ApiModelProperty(value="Age of the Employee")
    private Long age;
    @ApiModelProperty(value="Department of the Employee")
    private String dept;
    public Employee()
    {
        super();
    }
    public Employee(Long id, String name, Long age, String dept)
    {
        super();
        this.id = id;
        this.name = name;
        this.age = age;
        this.dept = dept;
    }
    public Long getId()
    {
        return id;
    }
    public void setId(Long id)
    {
        this.id = id;
    }
    public String getName()
    {
        return name;
    }
    public void setName(String name)
    {
        this.name = name;
    }
    public Long getAge()
    {
        return age;
    }
    public void setAge(Long age)
    {
        this.age = age;
    }
    public String getDept()
    {
        return dept;
    }
    public void setDept(String dept)
    {
        this.dept = dept;
    }
    @Override
    public String toString()
    {
        return "Employee [id=" + id + ", name=" + name + ", age=" + age + ", dept=" + dept + "]";
    }
}

Download Source Code

Springfox Swagger 2 for Spring RESTful Web Services

Spring RESTful Web Services

Creating table

Folder Structure:

EmployeeDAO.java

EmployeeDAOImpl.java

EmployeeController.java

Employee.java

web.xml

SpringConfig.xml

Configuration without Spring Boot

Configuring Swagger 2 for Spring REST

Adding Custom Information in Swagger

Swagger 2 Annotations for REST Endpoints

Swagger 2 Annotations for Model

Follow

Useful Links

About JavaInterviewPoint

Spring RESTful Web Services

Creating table

Folder Structure:

Other interesting articles which you may like …

EmployeeDAO.java

EmployeeDAOImpl.java

EmployeeController.java

Employee.java

web.xml

SpringConfig.xml

Configuration without Spring Boot

Configuring Swagger 2 for Spring REST

Adding Custom Information in Swagger

Swagger 2 Annotations for REST Endpoints

Swagger 2 Annotations for Model

Leave a Reply Cancel reply

Follow

Useful Links

About JavaInterviewPoint