目录
- 前言
- 1. @ApiModel注解
- 2. @ApiModelProperty注解
- 3. 实战
前言
在Java中,@ApiModel和@ApiModelProperty是Swagger框架(用于API文档的工具)提供的注解,用于增强API文档的生成和展示。这两者搭配使用更佳
(图片来源网络,侵删)使用两者注解,需导入swagger的依赖包:
io.swagger.core.v3 swagger-annotations 2.2.19
主要作用:开发者对API的模型和属性进行详细的描述,以便生成清晰的API文档。
(图片来源网络,侵删)1. @ApiModel注解
- @ApiModel注解用于对Java类进行标注,表示这个类是一个Swagger模型(Model)。通常用于描述一个数据对象或DTO(Data Transfer Object)。
示例代码:
import io.swagger.annotations.ApiModel; @ApiModel(description = "用户信息") public class User { // 类的属性... }
深入其源码:
package io.swagger.annotations; import java.lang.annotation.ElementType; import java.lang.annotation.Inherited; import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; @Target({ElementType.TYPE}) @Retention(RetentionPolicy.RUNTIME) @Inherited public @interface ApiModel { String value() default ""; String description() default ""; Class parent() default Void.class; String discriminator() default ""; Class[] subTypes() default {}; String reference() default ""; }
源码中的注解可看出:
- @Target注解
- @Retention注解
用于指定自定义注解的生命周期,即注解在程序运行时的保留策略。该源码表示运行时
- @Inherited注解
子类会继承该注解。默认情况下,注解不会被子类继承。
对应的属性值为:
- value属性:属性值,也就是该实体类的描述值,不写默认为实体类的名称,通常描述不清晰才需要value值
- description属性:描述值,与value不同,该description为较长描述值
- parent属性:用于指定被注解类的父类
- discriminator属性:多态情境区分多个子类
- subTypes属性:指定被注解类的子类
- reference属性:提供对被注解类的引用信息
2. @ApiModelProperty注解
- @ApiModelProperty注解用于对Java类的属性进行标注,表示这个属性是一个Swagger模型的属性。它可以用于描述属性的名称、说明、数据类型等信息
import io.swagger.annotations.ApiModelProperty; public class User { @ApiModelProperty(value = "用户ID", example = "123") private Long id; @ApiModelProperty(value = "用户名", example = "john_doe") private String username; // 其他属性... }
深入其源码:
@Target({ElementType.METHOD, ElementType.FIELD}) @Retention(RetentionPolicy.RUNTIME) public @interface ApiModelProperty { String value() default ""; String name() default ""; String allowableValues() default ""; String access() default ""; String notes() default ""; String dataType() default ""; boolean required() default false; int position() default 0; boolean hidden() default false; String example() default ""; /** @deprecated */ @Deprecated boolean readOnly() default false; AccessMode accessMode() default ApiModelProperty.AccessMode.AUTO; String reference() default ""; boolean allowEmptyValue() default false; Extension[] extensions() default {@Extension( properties = {@ExtensionProperty( name = "", value = "" )} )}; public static enum AccessMode { AUTO, READ_ONLY, READ_WRITE; private AccessMode() { } } }
其属性如下:
- value属性:
注解的默认属性,理解为注释的作用
- name属性:
指定属性或方法的名称,重写该属性名字
- allowableValues属性:
指定属性或方法的可接受值范围。
- access属性:
指定属性或方法的访问规则。
- notes属性:
提供对属性或方法的额外说明。
- dataType属性:
指定属性或方法的数据类型。
- required属性:
指定属性或方法是否为必需。
- position属性:
指定属性或方法在文档中的位置。
- hidden属性:
指定属性或方法是否应该在文档中隐藏。
- example属性:
提供属性或方法的示例值。
- readOnly属性(已过时):
指定属性或方法是否为只读。已过时,推荐使用 access 属性。
- accessMode属性:
指定访问模式,可以是 AUTO、READ_ONLY 或 READ_WRITE。
- reference属性:
提供属性或方法的引用信息。
- allowEmptyValue属性:
指定属性或方法是否允许为空值。
- extensions属性:
指定属性或方法的扩展信息,支持一组扩展属性。
- AccessMode枚举:
属性或方法的访问模式,包括 AUTO、READ_ONLY 和 READ_WRITE。
下面是一个简单的示例代码:
import io.swagger.annotations.ApiModelProperty; public class Example { @ApiModelProperty(value = "用户ID", example = "123", required = true) private Long userId; @ApiModelProperty(value = "用户名", example = "码农研究僧", readOnly = true) public String getUsername() { return "码农研究僧"; } }
3. 实战
比如应用在技术行业的某个模块,对应数据库中的entity实体类如下:
@Data @TableName("equipment_accident_record") @ApiModel(value = "AccidentRecord对象", description = "AccidentRecord对象") public class AccidentRecord extends BaseEntity { private static final long serialVersionUID = 1L; /** * 设备编号 */ @ApiModelProperty(value = "设备编号") private String equipmentNo; /** * 设备名称 */ @ApiModelProperty(value = "设备名称") private String equipmentName; /** * 设备机种 */ @ApiModelProperty(value = "设备机种") private String model; /** * 事故日期 */ @ApiModelProperty(value = "事故日期") private String dateTime; /** * 操作者 */ @ApiModelProperty(value = "操作者") private String operator; /** * 事故经过 */ @ApiModelProperty(value = "事故经过") private String content; /** * 损坏情况 */ @ApiModelProperty(value = "损坏情况") private String situation; /** * 事故原因 */ @ApiModelProperty(value = "事故原因") private String reason; /** * 事故类别 */ @ApiModelProperty(value = "事故类别") private String type; /** * 损失费用 */ @ApiModelProperty(value = "损失费用") private String expense; /** * 处理意见 */ @ApiModelProperty(value = "处理意见") private String opinion; /** * 主管技术员 */ @ApiModelProperty(value = "主管技术员") private String technician; }
其前端vo类别中的类如下:
@Data @ApiModel(value = "AccidentRecordVO对象", description = "AccidentRecordVO对象") public class AccidentRecordVO extends AccidentRecord { private static final long serialVersionUID = 1L; }
- value属性:
- @ApiModelProperty注解用于对Java类的属性进行标注,表示这个属性是一个Swagger模型的属性。它可以用于描述属性的名称、说明、数据类型等信息
- @ApiModel注解用于对Java类进行标注,表示这个类是一个Swagger模型(Model)。通常用于描述一个数据对象或DTO(Data Transfer Object)。