Spring Boot - Swagger @Parameter vs @Schema
Last Updated :
22 Aug, 2024
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. |
---|
Similar Reads
Spring Boot - Starter Parent
Spring Boot Starter Parent is a starter project that provides the default configuration for spring-based applications. It is added as a parent in the pom.xml file. The spring-boot-starter-parent defines spring-boot-dependencies as its parent. The spring-boot-starter-parent inherits dependency manage
3 min read
Spring Boot - Enabling Swagger2
Swagger is a versatile tool designed for simplifying the process of documenting and testing RESTful APIs. It shines as the preferred choice due to its exceptional support for creating interactive API documentation. This feature significantly enhances developers' ability to grasp and utilize your API
3 min read
Spring Boot - @Operation vs @ApiResponse in Swagger
Swagger is a powerful tool for documenting APIs in a standardized way. It allows developers to describe the structure of their APIs so that both machines and humans can understand and interact with them effectively. In the context of Swagger and OpenAPI, annotations play a crucial role in defining h
3 min read
How to Generate Spring Boot REST Client with Swagger?
Spring Boot is a powerful framework for building Java applications, particularly RESTful web services. When developing the REST APIs, it can be crucial to provide documentation that is both user-friendly and interactive. Swagger is an open-source that simplifies this by generating the API documentat
6 min read
JSON Parameters with Spring MVC
JSON (JavaScript Object Notation) is a lightweight data exchange format. We can interchange data from one application to another from client to server. We have many data interchange formats available in the market. Like properties files, XML files, YAML files, JSON files, etc. But when compared to o
14 min read
Spring Boot - Spring Data JPA
Spring Data JPA or JPA stands for Java Persistence API, so before looking into that, we must know about ORM (Object Relation Mapping). So Object relation mapping is simply the process of persisting any java object directly into a database table. Usually, the name of the object being persisted become
6 min read
Properties with Spring and Spring Boot
Java-based applications using the Spring framework and its evolution into the Spring Boot and the properties play a crucial role in configuring the various aspects of the application. Properties can allow the developers to externalize the configuration settings from the code. Understanding how to wo
4 min read
Spring vs Spring Boot vs Spring MVC
Are you ready to dive into the exciting world of Java development? Whether you're a seasoned pro or just starting out, this article is your gateway to mastering the top frameworks and technologies in Java development. We'll explore the Spring framework, known for its versatility and lightweight natu
8 min read
What is Spring Boot Profiles?
Spring Boot, a popular framework for building Java applications, offers a wealth of features that simplify development. Among these, "Profiles" stand out as a powerful tool for managing configurations in different environments. This article will delve into what profiles are, why they are crucial, an
4 min read
Spring Boot - Spring JDBC vs Spring Data JDBC
Understanding the difference between Spring JDBC and Spring Data JDBC is important for choosing the right approach to interact with relational databases in Spring Boot applications. Both frameworks serve the same purpose but differ significantly in terms of abstraction, ease of use, and developer pr
5 min read