一文读懂@Schema和@ApiModel的区别

后端

2022-12-07 20:33:22

@Schema与@ApiModel：理解其差异，提升API文档质量

简介

在API开发中，清晰准确的API文档至关重要。Swagger，一个流行的开源框架，通过其@Schema和@ApiModel注解提供了有效注释数据结构的方法。了解这些注解之间的差异至关重要，以便为您的API生成全面的文档。

@Schema与@ApiModel：相似与不同

相似之处：

@Schema和@ApiModel都是Swagger中的注解，用于数据结构。
它们允许您指定属性类型、和其他元数据，以便在Swagger UI或其他文档工具中清晰地显示数据结构。

不同之处：

规范版本： @Schema适用于Swagger 2.0规范，而@ApiModel适用于Swagger 3.0规范。
灵活性： @Schema更加灵活，因为它允许指定更广泛的数据类型和格式，如枚举和默认值。@ApiModel具有更有限的类型支持。
语法： 语法上，@Schema使用name和description属性，而@ApiModel使用value和description属性。

代码示例：

@Schema：

@Schema(name = "Person", description = "Represents a person")
public class Person {
    @Schema(required = true, description = "The person's name")
    private String name;
    @Schema(required = true, description = "The person's age")
    private int age;
}

@ApiModel：

@ApiModel(value = "Person", description = "Represents a person")
public class Person {
    @ApiModelProperty(required = true, value = "The person's name")
    private String name;
    @ApiModelProperty(required = true, value = "The person's age")
    private int age;
}