@Parameter and @Schema annotations in Spring Boot - Practice Problems & Coding Challenges

Challenge - 5 Problems

❓ component_behavior

intermediate

How does @Parameter affect API documentation?

Consider a Spring Boot REST controller method with a parameter annotated by @Parameter(description = "User ID"). What effect does this annotation have on the generated OpenAPI documentation?

Spring Boot

public ResponseEntity<User> getUser(@Parameter(description = "User ID") @PathVariable String id) {
    // method body
}

A It changes the parameter type in the API to a custom object.

B It automatically validates the parameter value before method execution.

C It adds a description to the parameter in the OpenAPI docs, helping API consumers understand its purpose.

D It hides the parameter from the generated API documentation.

💡 Hint

Think about how @Parameter is used to enhance API documentation metadata.

The @Parameter annotation is used to add metadata like descriptions to method parameters in OpenAPI documentation. It does not affect validation or parameter types directly.

📝 Syntax

intermediate

Correct usage of @Schema to define a model property

Which of the following code snippets correctly uses @Schema to specify that a field is required and has a maximum length of 50 characters?

Spring Boot

public class User {
    @Schema(required = true, maxLength = 50)
    private String name;
}

A @Schema(required = true, maxLength = 50)

B @Schema(required = "true", maxLength = 50)

C @Schema(required = true, maxLength = "50")

D @Schema(required = true, maxLength = 50, description = 100)

💡 Hint

Check the data types of the annotation attributes.

The @Schema annotation attributes require correct data types: 'required' is boolean, 'maxLength' is int. Passing strings or wrong types causes errors.

🔧 Debug

advanced

Why does this @Schema annotation cause a runtime error?

Given the code snippet below, why does the application fail to start? public class Product { @Schema(example = 12345) private String code; }

Spring Boot

public class Product {
    @Schema(example = 12345)
    private String code;
}

A The field 'code' must be public for @Schema to work.

B The example attribute expects a String value, but an integer is provided, causing a type mismatch error.

C The @Schema annotation requires a description attribute to work properly.

D The example attribute cannot be used on String fields.

💡 Hint

Check the expected data type for the example attribute in @Schema.

The example attribute in @Schema expects a String value. Providing an integer causes a type mismatch error during startup.

🧠 Conceptual

advanced

Difference between @Parameter and @Schema annotations

Which statement best describes the difference between @Parameter and @Schema annotations in Spring Boot OpenAPI integration?

A @Parameter and @Schema are interchangeable and serve the same purpose.

B @Parameter validates input values, and @Schema generates API documentation for endpoints.

C @Parameter is only for request bodies, and @Schema is only for response bodies.

D @Parameter is used to describe method parameters in API endpoints, while @Schema describes the structure of data models or properties.

💡 Hint

Think about what each annotation targets: parameters vs data models.

@Parameter annotates method parameters to add metadata for API docs, while @Schema annotates data model classes or fields to define their schema details.

❓ state_output

expert

What is the effect of combining @Parameter and @Schema on a method parameter?

Consider this method parameter in a Spring Boot controller: @GetMapping("/items/{id}") public Item getItem( @Parameter(description = "Item identifier") @Schema(example = "42", required = true) @PathVariable String id) { // method body } What will be the combined effect on the generated OpenAPI documentation for this parameter?

Spring Boot

@Parameter(description = "Item identifier")
@Schema(example = "42", required = true)
@PathVariable String id

A The parameter will have a description, be marked required, and show an example value in the OpenAPI docs.

B The @Schema annotation will override @Parameter, so only example and required are shown without description.

C Only the @Parameter description is used; @Schema is ignored on method parameters.

D The parameter will be hidden from the OpenAPI documentation due to conflicting annotations.

💡 Hint

Both annotations add complementary metadata for API documentation.

Using both @Parameter and @Schema on a method parameter enriches the OpenAPI docs with description, example, and required status together.

Practice

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

easy

A. To describe method parameters for API documentation

B. To define database entity fields

C. To configure security roles

D. To handle exceptions globally

Solution

1. Step 1: Understand the role of @Parameter

   The @Parameter annotation is used to add descriptive information about method parameters in API endpoints.

2. Step 2: Differentiate from other annotations

   It is not used for database, security, or exception handling but specifically for API documentation clarity.

3. Final Answer:

   To describe method parameters for API documentation -> Option A

4. Quick Check:

   @Parameter describes API method parameters = D [OK]

Hint: Remember: @Parameter is for method parameter docs [OK]

Common Mistakes:

• Confusing @Parameter with @Schema for data models
• Thinking @Parameter manages security or exceptions
• Using @Parameter for database field mapping

2. Which of the following is the correct way to add a description to a method parameter using @Parameter?

easy

A. @Parameter(value = "User ID") String userId

B. @Parameter(description = "User ID") String userId

C. @Parameter(desc = "User ID") String userId

D. @Parameter(text = "User ID") String userId

Solution

1. Step 1: Recall the correct attribute name

   The @Parameter annotation uses the attribute description to add text about the parameter.

2. Step 2: Verify syntax correctness

   Only @Parameter(description = "User ID") String userId uses description correctly; others use invalid attribute names.

3. Final Answer:

   @Parameter(description = "User ID") String userId -> Option B

4. Quick Check:

   @Parameter uses description attribute = A [OK]

Hint: Use description= for @Parameter text, not value or desc [OK]

Common Mistakes:

• Using 'value' instead of 'description' attribute
• Using non-existent attributes like 'desc' or 'text'
• Omitting the attribute name entirely

3. Given the code snippet:

@Parameter(description = "User's age", required = true) int age

What effect does the required = true have in API documentation?

medium

A. Marks the parameter as mandatory in the API docs

B. Sets a default value for the parameter

C. Makes the parameter optional

D. Hides the parameter from the API docs

Solution

1. Step 1: Understand the required attribute

   The required = true flag indicates that the parameter must be provided by the API caller.

2. Step 2: Effect on API documentation

   This makes the parameter appear as mandatory in generated API docs, guiding users to supply it.

3. Final Answer:

   Marks the parameter as mandatory in the API docs -> Option A

4. Quick Check:

   required=true means mandatory parameter = B [OK]

Hint: required=true means parameter must be provided [OK]

Common Mistakes:

• Thinking required=true sets default values
• Assuming it hides the parameter
• Confusing required=true with optional parameters

4. Identify the error in this usage of @Schema annotation:

@Schema(description = "User's email", required = "true")
private String email;

medium

A. The annotation must be placed on the getter method, not the field

B. The description attribute is missing

C. The required attribute should be a boolean, not a string

D. The email field must be public for @Schema to work

Solution

1. Step 1: Check attribute types in @Schema

   The required attribute expects a boolean value, not a string.

2. Step 2: Identify the error in the code

   Using required = "true" is incorrect; it should be required = true without quotes.

3. Final Answer:

   The required attribute should be a boolean, not a string -> Option C

4. Quick Check:

   @Schema required must be boolean, not string = C [OK]

Hint: Use true/false without quotes for boolean attributes [OK]

Common Mistakes:

• Putting boolean values in quotes
• Assuming @Schema only works on methods
• Thinking field visibility affects @Schema

5. You want to document a complex API model field that can be null but has a maximum length of 50 characters. Which @Schema annotation usage is correct?

hard

A. @Schema(description = "Optional comment", maxLength = 50, nullable = false) private String comment;

B. @Schema(description = "Optional comment", maxLength = "50", nullable = "true") private String comment;

C. @Schema(description = "Optional comment", maxLength = 50, required = true) private String comment;

D. @Schema(description = "Optional comment", maxLength = 50, nullable = true) private String comment;

Solution

1. Step 1: Understand attribute types for @Schema

   Attributes like maxLength expect an integer, and nullable expects a boolean.

2. Step 2: Match requirements with options

   The field can be null, so nullable = true is needed, and maxLength should be 50 as an integer.

3. Step 3: Eliminate incorrect options

   @Schema(description = "Optional comment", maxLength = "50", nullable = "true") private String comment; uses strings for boolean and integer, which is wrong. @Schema(description = "Optional comment", maxLength = 50, required = true) private String comment; marks it required (not nullable). @Schema(description = "Optional comment", maxLength = 50, nullable = false) private String comment; sets nullable false, disallowing null.

4. Final Answer:

   @Schema(description = "Optional comment", maxLength = 50, nullable = true) private String comment; -> Option D

5. Quick Check:

   Use correct types and nullable=true for optional fields = A [OK]

Hint: Use boolean and int types correctly in @Schema attributes [OK]

Common Mistakes:

• Using strings instead of boolean or int for attributes
• Confusing nullable and required attributes
• Setting nullable false when field can be null