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 + "]"; } }
Leave a Reply