Swagger + Spring Boot with example
Today, we will go through how to create API documentation using swagger and spring boot.
Swagger is a framework for describing our API by using a common language that is easy to read and understand by developers and testers, even they have weak source code knowledge.
- Spring Boot 2.1.1.RELEASE
- Spring 5.1.3.RELEASE
- Maven 3
- JDK 1.8
- Eclipse Oxygen
- Swagger 2
1)Project Structure
2)Maven/Dependency Management [pom.xml]
<?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
https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>2.1.1.RELEASE</version>
<!-- lookup parent from repository -->
</parent>
<groupId>com.knowledgefactory</groupId>
<artifactId>springboot-swagger</artifactId>
<packaging>jar</packaging>
<version>0.0.1-SNAPSHOT</version>
<name>springboot-swagger</name>
<description>Demo project for springboot-swagger</description>
<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter</artifactId>
</dependency>
<!-- spring mvc, rest -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.3.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.3.1</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
3)User Class
package com.knowledgefactory.knowledgefactorydemo;
public class User {
private String id;
private String name;
private String mail;
public String getId() {
return id;
}
public void setId(String id) {
this.id = id;
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getMail() {
return mail;
}
public void setMail(String mail) {
this.mail = mail;
}
public User(String id, String name, String mail) {
super();
this.id = id;
this.name = name;
this.mail = mail;
}
}
4)UserService Class
package com.knowledgefactory.knowledgefactorydemo;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import org.springframework.stereotype.Service;
@Service
public class UserService {
private List<User> topicList = new ArrayList<>(
Arrays.asList(new User("1", "knowledgefactory",
"knowledgefactory4upeoples@gmail.com"),
new User("2", "Spring", "demo@gmail.com"),
new User("3", "Java", "java@gmail.com")));
public List<User> getTopicList() {
return topicList;
}
public void setTopicList(List<User> topicList) {
this.topicList = topicList;
}
}
5)Controller
package com.knowledgefactory.knowledgefactorydemo;
import java.util.List;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.GetMapping;
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
@Api
public class Controller {
@Autowired
UserService service;
@GetMapping("/user")
@ApiOperation(value = "Find all User",
notes = "Retrieving the collection of User", response = User[].class)
@ApiResponses({ @ApiResponse(code = 200, message = "Success",
response = User[].class) })
public List<User> findAll() {
return service.getTopicList();
}
}
6)Main Class
package com.knowledgefactory.knowledgefactorydemo;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@EnableSwagger2
@SpringBootApplication
public class KnowledgefactorydemoApplication {
public static void main(String[] args) {
SpringApplication.run(KnowledgefactorydemoApplication.class, args);
}
@Bean
public Docket swagger() {
return new Docket(DocumentationType.SWAGGER_2).select().
apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any()).build()
.useDefaultResponseMessages(false);
}
}
7)Run
$ mvn spring-boot:run
8)Test
