@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
}

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;
    }
}

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
}

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;
    }
}

Hint

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

Practice

1. What is the main purpose of the @Operation annotation in Spring Boot APIs?

easy

A. To add descriptions and summaries to API endpoints for documentation

B. To handle database transactions automatically

C. To secure API endpoints with authentication

D. To configure server port settings

Solution

1. Step 1: Understand the role of @Operation

   The @Operation annotation is used to add descriptive metadata to API endpoints.

2. Step 2: Identify its main use

   It helps generate clear API documentation by providing summaries and detailed descriptions.

3. Final Answer:

   To add descriptions and summaries to API endpoints for documentation -> Option A

4. Quick Check:

   @Operation adds descriptions [OK]

Hint: Remember: @Operation documents APIs, not config or security [OK]

Common Mistakes:

• Confusing @Operation with security annotations
• Thinking it manages database or server settings
• Using it to handle authentication

2. Which of the following is the correct way to add a short summary and a detailed description using @Operation?

easy

A. @Operation(title = "Short info", details = "Detailed info")

B. @Operation(summary = "Short info", description = "Detailed info")

C. @Operation(info = "Short info", text = "Detailed info")

D. @Operation(header = "Short info", body = "Detailed info")

Solution

1. Step 1: Recall the correct attribute names

   The @Operation annotation uses summary for short info and description for detailed info.

2. Step 2: Match attributes to options

   Only @Operation(summary = "Short info", description = "Detailed info") uses summary and description correctly.

3. Final Answer:

   @Operation(summary = "Short info", description = "Detailed info") -> Option B

4. Quick Check:

   Use summary and description in @Operation [OK]

Hint: Use summary and description exactly [OK]

Common Mistakes:

• Using wrong attribute names like title or info
• Mixing up summary and description
• Omitting either summary or description

3. Given the code snippet:

@Operation(summary = "Get user", description = "Returns user details by ID")
@GetMapping("/user/{id}")
public User getUser(@PathVariable String id) { return userService.findById(id); }

What will the @Operation annotation affect?

medium

A. It will generate API documentation showing the summary and description for this endpoint

B. It will change the URL path to "/user/getUser" automatically

C. It will validate the user ID parameter before method execution

D. It will encrypt the response data automatically

Solution

1. Step 1: Understand @Operation effect on API docs

   The annotation adds metadata used by tools like Swagger to generate documentation.

2. Step 2: Check other options for correctness

   It does not change URL paths, validate parameters, or encrypt data.

3. Final Answer:

   It will generate API documentation showing the summary and description for this endpoint -> Option A

4. Quick Check:

   @Operation affects docs only [OK]

Hint: Remember: @Operation only documents, does not change behavior [OK]

Common Mistakes:

• Thinking it modifies URL or method behavior
• Assuming it validates inputs
• Believing it encrypts data

4. Identify the error in this usage of @Operation:

@Operation(summary = "Create item", description = 12345)
@PostMapping("/item")
public Item createItem(@RequestBody Item item) { return itemService.save(item); }

medium

A. The @PostMapping annotation is incorrect

B. The summary attribute is missing

C. The method return type should be void

D. The description value must be a string, not a number

Solution

1. Step 1: Check attribute types in @Operation

   The description attribute must be a string, but 12345 is a number.

2. Step 2: Verify other parts

   The summary is present, @PostMapping is correct, and return type can be Item.

3. Final Answer:

   The description value must be a string, not a number -> Option D

4. Quick Check:

   @Operation attributes require string values [OK]

Hint: Always use quotes for @Operation text values [OK]

Common Mistakes:

• Passing non-string values to summary or description
• Confusing HTTP method annotations
• Expecting void return type for create methods

5. You want to document an API endpoint that returns a list of products with a short summary and a detailed description including usage notes. Which @Operation annotation usage is best?

hard

A. @Operation(description = "Returns all products.")

B. @Operation(summary = "List products")

C. @Operation(summary = "List products", description = "Returns all products. Use filters to narrow results.")

D. @Operation(notes = "Returns all products with filters.")

Solution

1. Step 1: Identify required documentation details

   You need both a short summary and a detailed description with usage notes.

2. Step 2: Match attributes to requirements

   @Operation(summary = "List products", description = "Returns all products. Use filters to narrow results.") uses both summary and description properly to provide clear info.

3. Step 3: Check other options

   Options B and C provide only one attribute; D uses an invalid attribute notes.

4. Final Answer:

   @Operation(summary = "List products", description = "Returns all products. Use filters to narrow results.") -> Option C

5. Quick Check:

   Use both summary and description for full docs [OK]

Hint: Use both summary and description for complete API docs [OK]

Common Mistakes:

• Using only summary or description alone
• Using unsupported attributes like notes
• Leaving out usage details in description