Why API docs matter in Spring Boot - See It in Action

Why API docs matter

📖 Scenario: You are building a simple Spring Boot REST API for a bookstore. You want to make sure other developers can easily understand and use your API by adding clear documentation.

🎯 Goal: Create a Spring Boot REST controller with API documentation using OpenAPI annotations. This will help others know what your API does and how to use it.

📋 What You'll Learn

Create a Spring Boot REST controller class named BookController.

Add a GET endpoint /books that returns a list of book titles.

Create a configuration variable apiTitle with the value Bookstore API.

Use OpenAPI annotations to document the API title and the GET endpoint.

Add a final annotation to enable OpenAPI documentation generation.

💡 Why This Matters

🌍 Real World

API documentation is essential in real projects to help teams and external users understand how to interact with your backend services without confusion.

💼 Career

Knowing how to document APIs with OpenAPI is a valuable skill for backend developers, improving collaboration and speeding up development cycles.

1

Create the REST controller with a GET endpoint

Create a Spring Boot REST controller class named BookController with a GET endpoint /books that returns a list of strings: "Spring in Action", "Effective Java", and "Clean Code".

Spring Boot

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

@RestController
public class BookController {
    // Your code here
}

Need a hint?

Use @RestController on the class and @GetMapping("/books") on the method that returns a list of book titles.

2

Add API title configuration

Add a String variable named apiTitle with the value "Bookstore API" inside the BookController class.

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;

@RestController
public class BookController {
    // Add apiTitle variable here

    @GetMapping("/books")
    public List getBooks() {
        return List.of("Spring in Action", "Effective Java", "Clean Code");
    }
}

Need a hint?

Declare a private static final String variable named apiTitle and assign it the value "Bookstore API".

3

Add OpenAPI annotations to document the API

Add the OpenAPI annotation @Tag(name = apiTitle) on the BookController class and @Operation(summary = "Get list of books") on the getBooks method. Import these annotations from io.swagger.v3.oas.annotations.

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;

// Add @Tag annotation here
@RestController
public class BookController {
    private static final String apiTitle = "Bookstore API";

    // Add @Operation annotation here
    @GetMapping("/books")
    public List getBooks() {
        return List.of("Spring in Action", "Effective Java", "Clean Code");
    }
}

Need a hint?

Use @Tag(name = apiTitle) on the class and @Operation(summary = "Get list of books") on the method.

4

Enable OpenAPI documentation generation

Add the @OpenAPIDefinition annotation on the BookController class with an info property setting the title to apiTitle. Import @OpenAPIDefinition and Info from io.swagger.v3.oas.annotations.

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.List;
import io.swagger.v3.oas.annotations.tags.Tag;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.OpenAPIDefinition;
import io.swagger.v3.oas.annotations.info.Info;

// Add @OpenAPIDefinition annotation here
@Tag(name = apiTitle)
@RestController
public class BookController {
    private static final String apiTitle = "Bookstore API";

    @Operation(summary = "Get list of books")
    @GetMapping("/books")
    public List getBooks() {
        return List.of("Spring in Action", "Effective Java", "Clean Code");
    }
}

Need a hint?

Use @OpenAPIDefinition(info = @Info(title = apiTitle)) on the class to enable API docs.