Spring Boot RESTful API Documentation Using Swagger 2

Spring Boot With Swagger 2

What is Swagger?

Swagger allows you to describe the structure of your APIs so that machines can read them. The ability of APIs to describe their own structure is the root of all awesomeness in Swagger. 

Swagger is a specification for documenting REST API. It specifies the format (URL, method, and representation) to describe REST web services. It provides also tools to generate/compute the documentation from application code. 

Swagger scans your code and exposes the documentation on some URL. 

The Swagger documentation uses and implements HATEOAS: once a client reaches the documentation  homepage, it can follow the link to learn more about the API of the various resources the system exposes.

Project Structure

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/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.gaurav</groupId>
<artifactId>spring.boot.swagger</artifactId>
<version>0.0.1-SNAPSHOT</version>
<packaging>jar</packaging>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.1.RELEASE</version>
</parent>

<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.2.2</version>
</dependency>

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

<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>

application.properties

server.port=9595

EmployeeController.java

package com.gaurav.spring.boot.swagger.controller;

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

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class EmployeeController {

private static Map<Long, String> employeeMap = new HashMap<Long, String>();

@RequestMapping(method = RequestMethod.GET, value = "/rest/gaurav/list/employee")
public String listEmployees() {
employeeMap.put(new Long(1001), "Gaurav");
employeeMap.put(new Long(1234), "Aaditya");
employeeMap.put(new Long(11), "Shivam");
employeeMap.put(new Long(101), "Kumar");

return employeeMap.toString();
}

@RequestMapping(method = RequestMethod.POST, value = "/rest/gaurav/save/employee")
public String saveEmployeeName(@RequestParam Long id, @RequestParam String name) {
employeeMap.put(new Long(id), name);
return employeeMap.toString();
}

@RequestMapping(method = RequestMethod.PUT, value = "/rest/gaurav/update/employee")
public String updateEmployeeName(@RequestParam Long id, @RequestParam String name) {
String result = null;
if(employeeMap.get(id)!= null){
employeeMap.put(new Long(id), name);
return employeeMap.toString();
}else{
result = "Employee not found with the given ID:"+id;
return result;
}
}

@RequestMapping(method = RequestMethod.DELETE, value = "/rest/gaurav/delete/employee")
public String removeEmployeeName(@RequestParam Long id) {
String result = null;
if(employeeMap.get(id)!= null){
employeeMap.remove(new Long(id));
return employeeMap.toString();
}
else{
result = "Employee not found with the given ID:"+id;
return result;
}

}

}

SwaggerConfiguration.java

package com.gaurav.spring.boot.swagger.config;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

import com.google.common.base.Predicate;

import springfox.documentation.builders.ApiInfoBuilder;

import springfox.documentation.service.ApiInfo;

import springfox.documentation.spi.DocumentationType;

import springfox.documentation.spring.web.plugins.Docket;

import springfox.documentation.swagger2.annotations.EnableSwagger2;

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

import static com.google.common.base.Predicates.or;

@Configuration

@EnableSwagger2

public class SwaggerConfiguration {

@Bean

public Docket postsApi() {

return new Docket(DocumentationType.SWAGGER_2).groupName("public-api")

.apiInfo(apiInfo()).select().paths(postPaths()).build();

}

private Predicate<String> postPaths() {

return or(regex("/rest/api.*"), regex("/rest/gaurav.*"));

}

private ApiInfo apiInfo() {

return new ApiInfoBuilder().title("Spring Boot + Swagger API")

.description("Spring Boot & Swagger API reference for developers")

.termsOfServiceUrl("http://javatipsbygaurav.blogspot.com/")

.contact("cutegiftsmile@gmail.com").license("javatipsbygaurav License")

.licenseUrl("cutegiftsmile@gmail.com").version("1.0").build();

}

}

Application.java

package com.gaurav.spring.boot.swagger;

import org.springframework.boot.SpringApplication;

import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication

public class Application {

public static void main(String[] args) {

SpringApplication.run(Application.class, args);

}

}

After triggering the Application.java using

Right Click -> Run As -> Spring Boot App

We can hit the below URL. I configured tomcat at port 9595.

http://localhost:9595/swagger-ui.html

List of All Operations:

List Employees operation

Save Employee Operation

Update Employee Operation

Delete Employee Operation