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