@Parameter and @Schema annotations in Spring Boot - Mini Project: Build & Apply

Using @Parameter and @Schema Annotations in Spring Boot

📖 Scenario: You are building a simple Spring Boot REST API for a bookstore. You want to document your API parameters and model properties clearly for API users using OpenAPI annotations.

🎯 Goal: Create a Spring Boot controller method with a query parameter documented using @Parameter annotation and a model class with a field documented using @Schema annotation.

📋 What You'll Learn

Create a controller method with a query parameter named author documented with @Parameter annotation

Create a model class Book with a field title documented with @Schema annotation

Use exact annotation attributes as specified

Follow Spring Boot and OpenAPI annotation syntax

💡 Why This Matters

🌍 Real World

API documentation is essential for backend services so frontend developers and API consumers understand how to use the API correctly.

💼 Career

Knowing how to use @Parameter and @Schema annotations is important for backend developers working with Spring Boot to create well-documented REST APIs.

1

Create the Book model class

Create a public class called Book with a private String field named title.

Spring Boot

public class Book {
    // Your code here
}

Need a hint?

Define a class named Book and add a private field title of type String.

2

Add @Schema annotation to the title field

Add the @Schema(description = "Title of the book") annotation above the title field in the Book class.

Spring Boot

public class Book {
    // Add @Schema annotation here
    private String title;
}

Need a hint?

Use @Schema from io.swagger.v3.oas.annotations.media and add the description attribute.

3

Create a controller method with a query parameter

Create a Spring Boot REST controller class named BookController with a method getBooks that accepts a query parameter author of type String.

Spring Boot

import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;

@RestController
public class BookController {
    // Your code here
}

Need a hint?

Create a controller class with a method annotated with @GetMapping("/books") and a parameter author annotated with @RequestParam.

4

Add @Parameter annotation to the author query parameter

Add the @Parameter(description = "Author name to filter books") annotation above the author parameter in the getBooks method.

Spring Boot

import io.swagger.v3.oas.annotations.Parameter;

@RestController
public class BookController {
    @GetMapping("/books")
    public List getBooks(@RequestParam /* Add @Parameter here */ String author) {
        return List.of();
    }
}

Need a hint?

Import @Parameter from io.swagger.v3.oas.annotations and add it before the author parameter with the description attribute.