@Operation annotation for descriptions in Spring Boot - Practice Problems & Coding Challenges

Challenge - 5 Problems

🧠 Conceptual

intermediate

What is the purpose of the @Operation annotation's description attribute?

In Spring Boot with OpenAPI, what does the description attribute inside the @Operation annotation provide?

A It gives a detailed explanation of what the API endpoint does, shown in the generated API docs.

B It defines the security roles required to access the API endpoint.

C It sets the HTTP status code returned by the API endpoint.

D It specifies the database table linked to the API endpoint.

💡 Hint

Think about what users reading API docs would need to understand about an endpoint.

The description attribute in @Operation provides a human-friendly explanation of the API endpoint's purpose. This helps users understand the endpoint when viewing the generated OpenAPI documentation.

❓ component_behavior

intermediate

How does the @Operation description appear in the generated OpenAPI docs?

Given a Spring Boot controller method annotated with @Operation(description = "Fetch all products"), where will this description appear?

A As the summary text for the API endpoint in the Swagger UI documentation.

B As a tooltip when hovering over the endpoint URL in Swagger UI.

C As the detailed explanation under the endpoint's method in the Swagger UI docs.

D It does not appear anywhere in the generated docs.

💡 Hint

Consider where detailed descriptions usually show up in API docs.

The description attribute content appears as a detailed explanation under the endpoint's method in Swagger UI, helping users understand what the endpoint does beyond the summary.

📝 Syntax

advanced

Identify the correct usage of @Operation with description and summary

Which of the following code snippets correctly uses @Operation to set both summary and description attributes?

Spring Boot

public class ProductController {

    @Operation(???)
    public List<Product> getAllProducts() {
        return List.of();
    }
}

A @Operation(summary = "List products", description = "Returns all products available in the store")

B @Operation(description = "List products", summary = "Returns all products available in the store")

C @Operation(summary => "List products", description => "Returns all products available in the store")

D @Operation(summary: "List products", description: "Returns all products available in the store")

💡 Hint

Remember Java annotation syntax uses = for attributes.

In Java annotations, attributes are set using attributeName = value. Option A correctly uses this syntax. Options A and D use invalid syntax, and option A swaps summary and description values incorrectly.

🔧 Debug

advanced

Why does this @Operation description not show in Swagger UI?

A developer wrote this code but the description does not appear in Swagger UI:

@Operation(description = "Get user details")
@GetMapping("/user/{id}")
public User getUser(@PathVariable String id) { ... }

What is the most likely reason?

A The description attribute is misspelled and should be 'desc'.

B The OpenAPI dependency is missing or not configured properly in the project.

C The @GetMapping annotation must come before @Operation for it to work.

D The method must return ResponseEntity<User> for description to show.

💡 Hint

Think about what generates the Swagger UI docs.

If the OpenAPI or Swagger dependencies are missing or misconfigured, annotations like @Operation won't be processed, so descriptions won't appear. The attribute name is correct, annotation order does not matter, and return type does not affect description display.

❓ state_output

expert

What is the output in Swagger UI for this @Operation annotation?

Consider this Spring Boot controller method:

@Operation(summary = "Create user", description = "Creates a new user with given details.")
@PostMapping("/users")
public ResponseEntity createUser(@RequestBody User user) {
    // implementation
    return ResponseEntity.ok(user);
}

What will a user see in the Swagger UI for this endpoint?

A Only the summary 'Create user' will appear; the description is ignored by Swagger UI.

B Neither summary nor description will appear unless explicitly enabled in Swagger UI settings.

C The description will appear as the endpoint title, and summary will be ignored.

D The endpoint will show 'Create user' as the summary and 'Creates a new user with given details.' as the detailed description below it.

💡 Hint

Think about how Swagger UI displays summary and description from @Operation.

Swagger UI uses the summary as the main title for the endpoint and shows the description as a detailed explanation below it. Both attributes are displayed by default.

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