Spring Boot with Swagger UI and Swagger API Example

 

Spring Boot with Swagger UI and Swagger API Example

Introduction

Swagger is a powerful tool for API documentation and testing. It provides a user-friendly interface for interacting with your APIs, making it easier to test endpoints and understand the structure of your API. Integrating Swagger with Spring Boot enhances the development experience by allowing you to visualize and interact with your RESTful web services directly from a browser.

In this article, we'll walk through how to set up Swagger UI with a Spring Boot application and create a simple API example.

Setting Up Swagger in a Spring Boot Application

1. Create a New Spring Boot Project

First, create a new Spring Boot project using Spring Initializr or your preferred IDE. For this example, we'll use Maven as the build tool.

Dependencies to Include:

• Spring Web
• Spring Boot DevTools (optional, for development)
• Swagger 2 (Springfox Swagger UI)

Here's how you can define these dependencies in your pom.xml:

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

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

    <!-- Swagger UI -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>3.0.0</version>
    </dependency>

    <!-- Spring Boot DevTools (Optional) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-devtools</artifactId>
        <optional>true</optional>
    </dependency>
</dependencies>

2. Configure Swagger in Spring Boot

Next, create a configuration class to set up Swagger. This class will use the Swagger 2 configuration from Springfox.

Create a new class SwaggerConfig in the config package (or any package of your choice):

java
package com.example.demo.config;

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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }
}

3. Create a Sample REST Controller

Let's create a simple REST controller to test our Swagger setup. Create a new class HelloController:

java
package com.example.demo.controller;

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

@RestController
@RequestMapping("/api")
public class HelloController {

    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, World!";
    }
}

4. Run Your Application

Run your Spring Boot application. You can do this from your IDE or by using the command line:

bash
mvn spring-boot:run

5. Access Swagger UI

Open your browser and navigate to http://localhost:8080/swagger-ui/. You should see the Swagger UI displaying the API documentation for your application. You can interact with the /api/hello endpoint directly from this interface.

Example

Here’s a quick example of what the Swagger UI would look like with our HelloController:

• GET /api/hello
  • Response:
    • 200 OK: "Hello, World!"

Swagger UI provides a clean interface where you can try out the API endpoints and view the responses.

Conclusion

Integrating Swagger UI with Spring Boot is straightforward and adds great value to your development workflow. It enables you to document and test your APIs efficiently, providing a clear view of how your endpoints interact. With the setup complete, you can now easily manage and explore your API endpoints using Swagger’s intuitive UI.

For more advanced configurations and customizations, refer to the Springfox documentation and explore additional features that Swagger offers.