@Operation annotation for descriptions in Spring Boot - Mini Project: Build & Apply

Using @Operation Annotation for API Descriptions in Spring Boot

📖 Scenario: You are building a simple Spring Boot REST API for a bookstore. You want to add clear descriptions to your API endpoints so that users and developers understand what each endpoint does.

🎯 Goal: Learn how to use the @Operation annotation from io.swagger.v3.oas.annotations to add descriptions to your REST controller methods.

📋 What You'll Learn

Create a Spring Boot REST controller class named BookController.

Add a GET endpoint method named getBookById that returns a book by its ID.

Add an @Operation annotation with a description to the getBookById method.

Add a POST endpoint method named addBook to add a new book.

Add an @Operation annotation with a description to the addBook method.

💡 Why This Matters

🌍 Real World

Adding clear descriptions to API endpoints helps developers and users understand the purpose and usage of each endpoint, improving API usability and documentation quality.

💼 Career

Knowing how to document APIs with annotations like @Operation is valuable for backend developers working with Spring Boot and OpenAPI/Swagger documentation tools.

1

Create the BookController class with a GET endpoint

Create a Spring Boot REST controller class named BookController. Inside it, write a method getBookById that takes a Long id parameter and returns a string "Book with ID: " plus the id. Annotate the method with @GetMapping("/books/{id}") and the class with @RestController.

Spring Boot

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

Need a hint?

Use @RestController on the class and @GetMapping("/books/{id}") on the method. Use @PathVariable to get the ID from the URL.

2

Add an @Operation annotation with a description to the GET method

Add the @Operation annotation from io.swagger.v3.oas.annotations.Operation above the getBookById method. Set its description attribute to "Get a book by its ID."

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.v3.oas.annotations.Operation;

@RestController
public class BookController {
    // Add @Operation annotation with description here
    @GetMapping("/books/{id}")
    public String getBookById(@PathVariable Long id) {
        return "Book with ID: " + id;
    }
}

Need a hint?

Import io.swagger.v3.oas.annotations.Operation and add @Operation(description = "Get a book by its ID.") above the method.

3

Add a POST endpoint method to add a new book

Inside the BookController class, add a method named addBook that takes a String bookName parameter annotated with @RequestBody and returns a string "Added book: " plus the bookName. Annotate the method with @PostMapping("/books").

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import io.swagger.v3.oas.annotations.Operation;

@RestController
public class BookController {
    @Operation(description = "Get a book by its ID.")
    @GetMapping("/books/{id}")
    public String getBookById(@PathVariable Long id) {
        return "Book with ID: " + id;
    }

    // Add addBook method here
}

Need a hint?

Use @PostMapping("/books") and @RequestBody for the parameter.

4

Add an @Operation annotation with a description to the POST method

Add the @Operation annotation above the addBook method. Set its description attribute to "Add a new book to the store."

Spring Boot

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import io.swagger.v3.oas.annotations.Operation;

@RestController
public class BookController {
    @Operation(description = "Get a book by its ID.")
    @GetMapping("/books/{id}")
    public String getBookById(@PathVariable Long id) {
        return "Book with ID: " + id;
    }

    // Add @Operation annotation with description here
    @PostMapping("/books")
    public String addBook(@RequestBody String bookName) {
        return "Added book: " + bookName;
    }
}

Need a hint?

Add @Operation(description = "Add a new book to the store.") above the addBook method.