Spring Boot and Swagger 3 Example

How to Integrate Swagger (Springfox) with Spring Boot

A Clean, Simple Guide for Beginners

Documenting REST APIs is one of the most important parts of backend development. Instead of writing documentation manually, tools like Swagger allow you to automatically visualize, explore, and test your APIs from a browser.

In this article, we will walk through a simple and clean implementation of Swagger 2 using Springfox in a Spring Boot application.

---

🌟 What is Swagger?

Swagger is an open-source framework for designing, documenting, and testing REST APIs.

It provides:

• ✔️ Automatic API documentation

• ✔️ Interactive UI for testing endpoints

• ✔️ A live API sandbox

• ✔️ Zero manual documentation effort

Once Swagger is added, API consumers can discover endpoints, test requests, and understand request/response structures without reading any technical document.

---

🧱 Project Setup — Add Dependencies

Create a Spring Boot project and add the following dependencies in your pom.xml.

This example uses Spring Boot 1.4.1 and Springfox Swagger 2.2.2.

<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.vinod.test</groupId>
    <artifactId>springboot-swagger-test</artifactId>
    <version>0.0.1-SNAPSHOT</version>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>1.4.1.RELEASE</version>
    </parent>

    <dependencies>
        <!-- Spring Boot Web -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- Springfox Swagger 2 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.2.2</version>
        </dependency>

        <!-- Swagger UI -->
        <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>

---

⚙️ Step 2 — Create Swagger Configuration

Create a new configuration class SwaggerConfig.java under com.vinod.test.

This class:

• Enables Swagger

• Defines API info (title, description, version, contact, etc.)

• Sets endpoint filtering

package com.vinod.test;

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

    @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("/api/posts.*"), regex("/api/test.*"));
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SWAGGER API")
                .description("SWAGGER SIMPLE EXAMPLE")
                .termsOfServiceUrl("http://vinodkkumaran.blogspot.com/")
                .contact("kkvinod.kumaran@gmail.com")
                .license("KK VINOD License")
                .licenseUrl("kkvinod.kumaran@gmail.com")
                .version("1.0")
                .build();
    }
}

---

📝 Step 3 — Create a Sample REST Controller

This is a simple GET endpoint that Swagger will automatically document.

package com.vinod.test;

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

@RestController
public class HelloController {

    @RequestMapping(method = RequestMethod.GET, value = "/api/test")
    public String sayHelloWorld() {
        return "Hello world from Swagger Example";
    }
}

---

🚀 Step 4 — Create Spring Boot Main Class

package com.vinod.test;

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

@SpringBootApplication
public class MySwaggerApplication {

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

---

▶️ Step 5 — Run the Application

Start the Spring Boot app:

mvn spring-boot:run

Open your browser and go to:

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

You will see Swagger UI with your GET /api/test endpoint documented and ready to test.

---

🖼️ How Swagger UI Looks

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