How to integrate Swagger 2 with Spring Boot

In this article, we will see how to integrate Swagger 2 with Spring Boot to generate a simple api documentation.

spring boot with swagger

What is Swagger ?

Swagger is set of open source tools that helps with creating documentation for your REST services.

Lets start with creating a Spring Tool Web application. You can refer the following article for the same.

Spring Boot Hello World Web Application
 

Adding Swagger 2 Maven Dependency

We will be using Springfox implementation in this example.

For integrating with Swagger 2, include the following dependencies in pom.xml :

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

Here is how the complete pom.xml looks like at this point.

<?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>com.example</groupId>
  <artifactId>SpringBootHello</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  <packaging>jar</packaging>

  <name>SpringBootHello</name>
  <description>Demo project for Spring Boot</description>

  <parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>1.5.8.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-web</artifactId>
    </dependency>

    <dependency>
      <groupId>org.springframework.boot</groupId>
      <artifactId>spring-boot-starter-test</artifactId>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.4.0</version>
      <scope>compile</scope>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.4.0</version>
      <scope>compile</scope>
    </dependency>
  </dependencies>

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

</project>

 

Spring Boot Application

The Spring Boot Application file will be autogenerated when you create the project. Here is the code for reference :

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootHelloApplication {

  public static void main(String[] args) {
    SpringApplication.run(SpringBootHelloApplication.class, args);
  }
}

Swagger Integration

Lets create a HelloController class with a GET method sayHello().

package com.example.demo;

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;

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

@Api
@RestController
public class HelloController {
  @RequestMapping(method = RequestMethod.GET, path = "/hello")
  @ApiOperation(value = "Respond Hello <Name> !!",
          notes = "Returns a JSON object with a string Hello followed by provided name. "
          + "Uses 'World' if a name is not specified")
  @ApiResponses(value = { 
      @ApiResponse(code = 200, message = "Success"),
      @ApiResponse(code = 404, message = "Service not available"),
      @ApiResponse(code = 500, message = "Unexpected Runtime error") })
  public String sayHello(@RequestParam(value = "name", defaultValue = "World") String name) {
    return "Hello " + name;
  }
}

Lets create a new class to provide the Swagger configurations annotate it will @Configuration and @Swagger2.

package com.example.demo;

import org.springframework.context.annotation.Configuration;

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;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
  public Docket helloApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.ant("/hello/*"))
                .build();
             
    }
}

Running the SpringBootHelloApplication class with start the SpringBootHelloApplication on the included Tomcat server.

We can test the application by going to the following url in the browser :

http://localhost:8080/hello?name=John

It should print “Hello John”.

It will append any name provided in the url to the string “Hello” and display. If no name is provided, it will display “Hello World”.
 

Swagger Output

For checking the generated Swagger documentation, open this url in the browser :

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

swagger output

swagger output 2

© 2017, https:. All rights reserved. On republishing this post, you must provide link to original post

One comment

  1. […] How to integrate Swagger with Spring Boot […]

Leave a Reply.. code can be added in <code> </code> tags

%d bloggers like this: