@Parameter and @Schema annotations in Spring Boot

Introduction

These annotations help describe API inputs and outputs clearly. They make your API easier to understand and document.

When you want to explain what a method parameter means in your API.

When you want to add details like example values or descriptions to your API fields.

When generating API documentation automatically with tools like Swagger.

When you want to control how your API parameters appear in the docs.

When you want to specify validation or format details for API data.

Syntax

Spring Boot

@Parameter(name = "paramName", description = "Description here", required = true)
@Schema(description = "Field description", example = "exampleValue", required = true)

@Parameter is used on method parameters to describe them.

@Schema is used on model fields or parameters to add details like examples or descriptions.

Examples

This describes the 'id' path variable as a required user ID.

Spring Boot

@Parameter(name = "id", description = "User ID", required = true)
public ResponseEntity<User> getUser(@PathVariable String id) { ... }

This adds a description and example to the 'name' field in the User model.

Spring Boot

public class User {
  @Schema(description = "User's full name", example = "Jane Doe")
  private String name;
}

This describes an optional query parameter 'page' with an example value.

Spring Boot

@Parameter(description = "Page number for pagination", example = "1", required = false)
@RequestParam int page

Sample Program

This Spring Boot controller uses @Parameter to describe the path variable 'id'. The User class uses @Schema to add descriptions and examples to its fields. This helps generate clear API docs.

Spring Boot

import org.springframework.web.bind.annotation.*;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.media.Schema;
import org.springframework.http.ResponseEntity;

@RestController
@RequestMapping("/users")
public class UserController {

  @GetMapping("/{id}")
  public ResponseEntity<User> getUser(
    @Parameter(name = "id", description = "The unique ID of the user", required = true)
    @PathVariable String id) {
    User user = new User(id, "Alice Smith");
    return ResponseEntity.ok(user);
  }
}

class User {
  @Schema(description = "User identifier", example = "123")
  private String id;

  @Schema(description = "Full name of the user", example = "Alice Smith")
  private String name;

  public User(String id, String name) {
    this.id = id;
    this.name = name;
  }

  public String getId() { return id; }
  public String getName() { return name; }
}

Important Notes

Use @Parameter on controller method parameters to describe API inputs.

Use @Schema on model fields to add detailed info like examples and descriptions.

These annotations improve auto-generated API docs and help others understand your API.

Summary

@Parameter describes API method parameters.

@Schema describes data model fields with examples and descriptions.

Both help create clear, useful API documentation automatically.