Spring Boot - Swagger @Parameter vs @Schema

In API development, Swagger is widely used to document the RESTful APIs. Two essential annotations that come into play when defining the API operations and their models are @Parameter and @Schema. Understanding the difference between these annotations is crucial for the developers to accurately describe the behavior and structure of their APIs:

• @Parameter: It is primarily used to describe the parameters of an API operation, such as query parameters, path variables, requests, headers, etc.
• @Schema: It can be mainly used to define the schema of the data model or object in the API providing the metadata such as type, format, and constraints.

Understanding @Parameter vs @Schema in Swagger

In Swagger, two of the most frequently used annotations are @Parameter and @Schema. These annotations can serve distinct purposes but work together to create comprehensive API documentation. Here the detailed exploration of each and how they differ in their roles and applications.

1. @Parameter: Describing API Operation Parameters

The @Parameter annotation can be used to describe the parameters that are part of the API operation, these parameters can be of the various types such as query parameters, path variables, request headers, or even the cookie parameters. This annotation can allows the developers to provide the metadata about these parameters such as their description, whether they are required, their data type.

Key Features of @Parameter:

• Targeted Use: @Parameter annotation can be specifically used within the methods in controller classes to describe the parameters that the method expects.
• Applicable to Various Parameter Types: It can be applied to the parameters passed via query strings (@RequestParam), path variables (@PathVariable), header (@RequestHeader) or cookies.
• Descriptive Metadata: We can describe the parameters purpose and specify whether its required, set the default value and provide the example values.

Example Usage:

@GetMapping("/products")
public ResponseEntity<Product> getProductById(
    @Parameter(description = "ID of the product to retrieve", required = true, example = "12345")
    @RequestParam String id) {
    // Method implementation
    return ResponseEntity.ok(new Product(id, "Laptop", 999.99));
}

In this example:

• The @Parameter annotation can be used to provide the detailed description of the id parameter which is the query parameter.
• It can specifies that the id is required, gives the example value, and provides the brief description of its purpose.

2. @Schema: Defining Data Model Schema

The @Schema annotation can be used to define the schema of the data model or an object that is used in the API. It can provides the detailed metadata about the data model such as the type of each property, constraints, descriptions, and example values. This annotation can be typically applied at the class level and the field level.

Key Features of @Schema:

• Targeted Use: @Schema can be mainly used in the model classes to describe the structure and constraints of the data that the API handles such as the request bodies and response bodies.
• Rich Metadata: It can provides the comprehensive set of the metadata for each property, including the data type, allowable values, description and examples.
• Support for Complex Types: It can describe the complex data types, including the nested objects and arrays, with full control over the description and constraints of the each element.
• Validation Integration: It can integrates the seamlessly with validation annotations like @NotNull, @Size and @Pattern, allowing you to define the validation rules directly with the schema.

Example Usage:

public class Product {

    @Schema(description = "Unique identifier of the product", example = "12345")
    private String id;

    @Schema(description = "Name of the product", example = "Laptop", required = true)
    private String name;

    @Schema(description = "Price of the product in USD", example = "999.99")
    private Double price;

    // Getters and setters...
}

In this example:

• The @Schema annotation can be used to describe the each property of the Product class.
• The id property can be described as the unique identifier with the example value provided.
• The name property is required and its example values is specified.
• The price propery has the example value and is described as being in the USD.

Difference Between @Parameter and @Schema