Creating a RESTful API with Spring Boot and Swagger

Welcome, Java developers! In this post, we’ll explore how to create a RESTful API using Spring Boot and document it using Swagger. Swagger provides a user-friendly interface for interacting with and visualizing RESTful APIs, making it easier for developers to understand your endpoints.

What is Swagger?

Swagger (now known as OpenAPI) is an open-source API specification that provides a standard way to document REST APIs. It allows clients to understand the capabilities of your service without needing to read documentation, making integration much smoother.

Why Use Swagger?

• Interactive Documentation: Automatically generate interactive API documentation that helps developers quickly learn how to use your API.
• Ease of Testing: API consumers can test your API directly from the documentation interface.
• Standardization: Following the OpenAPI specification helps maintain a standard approach to API documentation.

Setting Up Swagger in a Spring Boot Project

Let’s walk through the process of creating a Spring Boot application with Swagger integrated.

Step 1: Create a Spring Boot Project

Use Spring Initializr to create a new Spring Boot project and choose the following dependencies:

• Spring Web
• Springdoc OpenAPI UI

Step 2: Add Dependencies

Your pom.xml should look like this:

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.5.10</version>
</dependency>

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

Creating a Sample REST Controller

Next, we’ll create a simple REST controller to expose API endpoints:

import org.springframework.web.bind.annotation.*;
import java.util.ArrayList;
import java.util.List;

@RestController
@RequestMapping("/api/products")
public class ProductController {
    private List<String> products = new ArrayList<>();

    @GetMapping
    public List<String> getAllProducts() {
        return products;
    }

    @PostMapping
    public String addProduct(@RequestBody String product) {
        products.add(product);
        return "Product added: " + product;
    }
}

This controller exposes two endpoints: one for retrieving all products and one for adding a new product.

Documenting Your API with Swagger

Swagger automatically generates API documentation based on your controller annotations. You can customize the documentation further using annotations from org.springdoc.core.annotations.. For instance, you can specify API details using the @OpenAPIDefinition annotation:

import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;
import io.swagger.v3.oas.annotations.info.Contact;

@OpenAPIDefinition(
    info = @Info(
        title = "Product API",
        version = "1.0",
        description = "API for managing products",
        contact = @Contact(
            name = "Support Team",
            email = "support@example.com"
        )
    )
)
public class Application {
    // Main application code
}

Testing Your Application and Swagger UI

Run your Spring Boot application and access the Swagger UI at:

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

Here, you can view and interact with your API endpoints, seeing real-time examples of requests and responses.

Best Practices for API Documentation

• Keep Documentation Updated: Ensure your API documentation is updated whenever you make changes to your API.
• Provide Descriptive Messages: Use clear and descriptive names for endpoints and parameters.
• Include Examples: Provide examples of both requests and responses to assist developers in understanding how to use your API.

Conclusion

By integrating Swagger into your Spring Boot application, you enhance your RESTful API’s usability and maintainability, allowing clients to interact with your API seamlessly. This tutorial provides you the foundational steps to implement API documentation effectively.

Want to learn more about Java Core? Join the Java Core in Practice course now!

To learn more about ITER Academy, visit our website.