@Schema 注解通常用于Java应用中的API文档生成，特别是在使用开放API规范（OpenAPI Specification，又称Swagger）。

@Schema 注解属于 io.swagger.v3.oas.annotations.media包，通常用于描述模型的属性，定义模型在API文档中的表示方式。以下是 @Schema 注解的一些常见属性以及其功能：

1. description:

   • 用于为字段提供详细描述。可以帮助API用户理解字段的用途。

   @Schema(description = "用户的唯一标识符")  
   private Long id;  

2. example:

   • 提供字段的示例值，帮助用户更好地理解该字段应包含的数据是什么。

   @Schema(example = "42")  
   private Integer age;  

3. title:

   • 为模式或属性提供显示用的标题。

   @Schema(title = "年龄")  
   private Integer age;  

4. type:

   • 指定属性的数据类型。如果没有指定，将基于Java的类型自动推断。

   @Schema(type = "integer")  
   private Integer age;  

5. format:

   • 定义属性的格式，通常与 type 属性结合使用。

   @Schema(type = "string", format = "date-time")  
   private LocalDateTime createdDate;  

6. required:

   • 指定该字段是否是必需的。

   @Schema(required = true)  
   private String name;  

7. allowableValues:

   • 定义属性可接受的值列表，通常在字段是常量或枚举时使用。

   @Schema(allowableValues = {"admin", "user", "guest"})  
   private String role;  

8. hidden:

   • 指定属性是否在API文档中隐藏。

   @Schema(hidden = true)  
   private String internalCode;  

9. deprecated:

   • 指定这个属性是否已被弃用。

   @Schema(deprecated = true)  
   private String legacyCode;  

10. defaultValue:

    • 指定该属性的默认值。

    @Schema(defaultValue = "guest")  
    private String role;  

在构建RESTful API时，通过使用 @Schema 注解，开发人员可以生成更为详尽和用户友好的API文档。这不仅提升了API的可读性，还可以帮助前端开发人员和其他API消费者更容易地理解和使用API。

需要注意的是，要生成API文档，通常需要配置Swagger/OpenAPI工具，以解析代码中的注解并生成相应的文档界面。