An article explains the @Schema annotation in JAVA in detail

summary

@SchemaAnnotations are an important annotation provided by Swagger (now renamed OpenAPI) to define and describe data models in API interfaces. pass@SchemaAnnotation, we can add description information to the class or field, optimize the generated API documents, so that developers can understand and use interfaces.

This blog starts from the perspective of a novice and explains in detail@SchemaThe usage of   includes the functions of annotations, applicable scenarios, common configuration items and code examples, which helps everyone get started quickly and master its core knowledge points.

introduction

Documentation is an important part in RESTful API development. With Swagger, we can generate API documents directly through code.@SchemaAnnotations are the core components used to describe fields and their behavior in the API model.

In this article, you will learn:

• What is@SchemaAnnotation?
• Why do you need to use it@Schema？
• How to use it in a project?

By reading this article, you will be@SchemaHave a comprehensive understanding and be able to apply it proficiently in the project.

1. What is @Schema annotation?

1.1 Introduction

@SchemaIt is an annotation provided by Swagger and belongs to OpenAPI.Bag. It is used to define the representation of a data model (Java class or field) in API documents, including name, description, required, default values, etc.

1.2 Advantages

• Intuitive documentation: Automatically generate intuitive API documents through simple annotations.
• Reduce misunderstandings: Add description information to the fields to avoid understanding deviations between developers.
• Standardized development: Define unified rules and descriptions for the interface to improve team collaboration efficiency.

2. Usage scenarios

2.1 Data model description

@SchemaUsually used to describe classes and fields to clearly display the data structure in the generated API documentation.

• Class Level: Provides description for the entire model.
• Field Level: Add a detailed description to the fields in the class.

2.2 Cooperate with other notes

@SchemaUsually with@RequestBody、@ApiResponseand other annotations are used in conjunction with the construction of more complete API documents.

3. Core configuration items

@SchemaMultiple attributes are provided, and the following are common configuration items:

4. Sample code

4.1 Basic usage: Description of classes and fields

The following code shows how to use it@SchemaAdd descriptions for classes and fields:

import .;

@Schema(title = "User Entity", description = "Describe the basic information of the user")
public class User {

    @Schema(title = "User ID", description = "User's unique identity", example = "1001", required = true)
    private Long id;

    @Schema(title = "username", description = "User's Name", example = "Zhang San", defaultValue = "Anonymous User")
    private String name;

    @Schema(title = "User Age", description = "User's age", example = "25")
    private Integer age;

    // Getters and Setters
}

Examples of generated API documentation are as follows:

4.2 Use with @RequestBody

In the controller,@SchemaUsually combined@RequestBodyUse to describe the structure of the request body:

import .*;
import .;

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

    @PostMapping
    @Operation(summary = "Create a user", description = "Create a new user based on user information in the request body")
    public String createUser(@RequestBody @Schema(description = "User Information", required = true) User user) {
        return "User creation successfully: " + ();
    }
}

4.3 Description of nested models

For nested models (such as one class contains fields from another class),@SchemaField relationships can also be defined:

@Schema(title = "Address Entity", description = "Describe the user's address information")
public class Address {

    @Schema(title = "City", description = "City where the user is located", example = "Shanghai")
    private String city;

    @Schema(title = "post code", description = "The user's postal code", example = "200000")
    private String postalCode;
}

@Schema(title = "User Entity", description = "Describe the basic information and address information of the user")
public class User {

    @Schema(title = "User ID", description = "User's unique identity", example = "1001", required = true)
    private Long id;

    @Schema(title = "username", description = "User's Name", example = "Zhang San")
    private String name;

    @Schema(title = "User Address", description = "User's address information")
    private Address address;

    // Getters and Setters
}

5. Frequently Asked Questions

5.1 Why does the description of @Schema not appear in the document?

The reasons may be:

• Swagger's version is too low.
• Missing dependencies or not properly configured Swagger.

5.2 Is it possible to use @Schema for enumeration classes?

Can.@SchemaPossible values ​​that can be used to describe enumerations.

@Schema(title = "Gender Enumeration", description = "Gender of the user")
public enum Gender {
    MALE, FEMALE
}

Summarize

pass@SchemaAnnotation, we can add detailed description information to the API data model, significantly improving the readability and intuitiveness of generated documents. In actual projects,@SchemaIt is a key tool in the API document toolchain. Proficiency in it can allow you to quickly generate standardized interface documents while avoiding the problem of documents being disconnected from code.

If you have questions about the content of this article, or want to learn more techniques in depth, please scan the code to add my WeChat and let’s discuss it together!

References

• OpenAPI official documentation
• Spring Boot and Swagger integration
• Java Enum type usage tips

This is all about this article about @Schema annotation in JAVA. For more information about @Schema annotation related to JAVA, please search for my previous articles or continue browsing the related articles below. I hope everyone will support me in the future!