@Parameter and @Schema annotations in Spring Boot - Interactive Code Practice

Practice - 5 Tasks

1fill in blank

easy

Complete the code to add a description to a method parameter using @Parameter annotation.

Spring Boot

@Parameter(description = "[1]")
public void getUser(String userId) {}

Drag options to blanks, or click blank then click option'

AUser identifier

BUser name

CUser age

DUser email

Attempts:

3 left

💡 Hint

Common Mistakes

Using unrelated descriptions like 'User name' when the parameter is an ID.

Leaving the description empty.

The @Parameter annotation's description attribute is used to describe the parameter. Here, "User identifier" clearly describes the purpose of the parameter.

2fill in blank

medium

Complete the code to specify the example value for a schema using @Schema annotation.

Spring Boot

@Schema(example = "[1]")
private String status;

Drag options to blanks, or click blank then click option'

Anull

B123

Ctrue

Dactive

Attempts:

3 left

💡 Hint

Common Mistakes

Using numeric or boolean values as examples for string fields.

Using 'null' as an example which is not informative.

The example attribute in @Schema provides a sample value for the field. "active" is a meaningful example for a status field.

3fill in blank

hard

Fix the error in the annotation to correctly mark a parameter as required using @Parameter.

Spring Boot

@Parameter(required = [1])
public void updateUser(String userId) {}

Drag options to blanks, or click blank then click option'

A"true"

Btrue

CTrue

DTRUE

Attempts:

3 left

💡 Hint

Common Mistakes

Using quotes around true making it a string.

Using uppercase True or TRUE which are invalid.

The required attribute expects a boolean value without quotes. Using true (lowercase) is correct.

4fill in blank

hard

Fill both blanks to define a schema with a description and a minimum value.

Spring Boot

@Schema(description = "[1]", minimum = "[2]")
private int age;

Drag options to blanks, or click blank then click option'

AUser age

B18

CMinimum age allowed

D0

Attempts:

3 left

💡 Hint

Common Mistakes

Using numeric values without quotes for minimum.

Using unrelated descriptions.

The description explains the field, and minimum sets the lowest allowed value. "User age" and "18" are appropriate here.

5fill in blank

hard

Fill all three blanks to create a parameter annotation with a name, description, and required flag.

Spring Boot

@Parameter(name = "[1]", description = "[2]", required = [3])
public void deleteUser(String id) {}

Drag options to blanks, or click blank then click option'

AuserId

BThe ID of the user to delete

Ctrue

Dfalse

Attempts:

3 left

💡 Hint

Common Mistakes

Using false for required when the parameter is mandatory.

Mismatching the name with the actual parameter variable.

The name attribute names the parameter, description explains it, and required marks it as mandatory. "userId", "The ID of the user to delete", and true are correct.

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