Implementing API Documentation with Springdoc OpenAPI in Spring Boot

API documentation is essential for any RESTful service, as it provides users and developers with a clear understanding of how to interact with your API. Springdoc OpenAPI is a library that automatically generates OpenAPI documentation for Spring Boot applications based on your REST controllers. In this post, we will explore how to implement Springdoc OpenAPI in a Spring Boot application for robust API documentation.

What is OpenAPI?

OpenAPI is a specification for building APIs with a defined structure, which allows both humans and machines to understand the capabilities of a service without access to its source code. It provides a standardized format for API documentation, enabling better collaboration and integrations across different services and platforms.

Setting Up Springdoc OpenAPI in Spring Boot

Follow these steps to integrate Springdoc OpenAPI into your Spring Boot application:

1. Create a New Spring Boot Project

Use Spring Initializr to create a new Spring Boot application with the following dependencies:

• Spring Web

2. Adding Springdoc OpenAPI Dependency

Add the Springdoc OpenAPI dependency in your pom.xml:

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

3. Configuring OpenAPI Properties

In your application.properties file, you can define various configurations for Springdoc.

springdoc.api-docs.path=/v3/api-docs
springdoc.swagger-ui.path=/swagger-ui.html

Creating REST APIs

For demonstration, let’s create a simple REST API to manage books. Create a Book model and a corresponding controller:

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Book {
    private Long id;
    private String title;
    private String author;
}

Next, create a controller for managing the books:

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

@RestController
@RequestMapping("/api/books")
public class BookController {
    private List<Book> bookList = new ArrayList<>();

    @PostMapping
    public Book addBook(@RequestBody Book book) {
        bookList.add(book);
        return book;
    }

    @GetMapping
    public List<Book> getBooks() {
        return bookList;
    }
}

Viewing API Documentation

Run your Spring Boot application and navigate to:

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

You will see the Swagger UI loaded with the endpoints defined in your application, allowing you to interact with the API and see the request/response structure.

Conclusion

Integrating Springdoc OpenAPI with your Spring Boot application provides a powerful way to document and manage your RESTful APIs effectively. It enhances collaboration and allows for better onboarding for new users. By following the steps outlined in this post, you can set up a professional API documentation system with minimal effort.

For deeper exploration and learning about working with Springdoc OpenAPI and advanced API documentation strategies, check out the extensive resources offered at ITER Academy.

To learn more about ITER Academy, visit our website.