Open In App

Spring Boot - Swagger @Parameter vs @Schema

Last Updated : 22 Aug, 2024
Comments
Improve
Suggest changes
Like Article
Like
Report

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

Aspect

@Parameter

@Schema

Primary Purpose

It describes the parameters used in the API operations (eg: query, path, header parameters).

It defines the schema of the data models (eg: request/response bodies).

Scope of Use

It can be used within the controller methods to the describe method parameters.

It can be used within the model classes to describe the structure and constraints of the data models.

Target

It focuses on the input parameters for the API operations.

It focuses on the data structure of the objects passed to or returned from API operations.

Annotations Relationship

It includes the @Schema annotation within it to further describe the complex types.

It does not include @Parameter works independently to describe the model properties.

Location

It applied directly to the method parameters in the controller classes.

It applied to fields or entire classes in the data model classes.

Complexity

Simpler, focusing on the describing the input parameters with basic metadata.

More complex, providing the detailed metadata for every aspect of the data model, including the nested types and arrays.

Flexibility

It is limited in describing the complex types; requires the @Schema for more detailed descriptions.

It is highly flexible and capable of the describing complex types; including the nested objects and arrays.

Validation Integration

It can work with validation annotations on the method parameters.

It fully integrates with the validation annotations within model classes.

Usage Context

Best suited for the simple parameters like query parameters, path variables and headers.

It is ideal for detailed descriptions of the data models used in the request/response bodies.

Documentation Impact

It directly impacts how parameters are documented in the Swagger UI for API methods.

It directly impacts how data models are documented and visualized in the Swagger UI.


Next Article

Similar Reads