swagger-codegen 生成的 Java 嵌套数组模型解析:以 ArrayOfArrayOfNumberOnly 为例
swagger-codegen 生成的 Java 嵌套数组模型解析:以 ArrayOfArrayOfNumberOnly 为例
导读
ArrayOfArrayOfNumberOnly 是 swagger-codegen 官方样例 okhttp4-gson Java 客户端中一个极具代表性的数据模型:它由 OpenAPI/Swagger 规范中的「数组嵌套数组」定义驱动生成,最终映射为 Java 中的 List<List<BigDecimal>> 类型。本文以该模型为切入口,完整解读其属性定义、生成源码的每一个方法、JSON 序列化行为与生成环境,帮助你理解 swagger-codegen 在遇到嵌套数组(array of array)类型时究竟会生成怎样的 Java 代码,以及如何在实际项目中正确使用它。
模型概述:一个只含嵌套数组字段的简单对象
ArrayOfArrayOfNumberOnly 是 Petstore 测试套件中用于验证「嵌套数组类型」生成的模型。它只有一个属性 arrayArrayNumber,类型为 List<List<BigDecimal>>,即外层是列表、内层仍是列表、最内层元素是 BigDecimal 数字,整体对应规范中的 type: array 且 items 之下再嵌套 items 的结构。
该模型对应的生成文档位于 ArrayOfArrayOfNumberOnly.md,属性定义如下:
| 名称 | Java 类型 | 说明 | 备注 |
|---|---|---|---|
| arrayArrayNumber | [List<List<BigDecimal>>] | 二维数字列表(外层与内层均为数组,最内层元素为 BigDecimal) |
可选(optional),默认 null |
从语义上看,该模型专门用于验证两层嵌套数组的生成正确性:规范声明一个对象属性,其值是「数字的数组的数组」,生成器需要据此推导出正确的 Java 泛型类型 List<List<BigDecimal>>,并为其生成完整的存取方法链。
规范来源:嵌套数组在 OpenAPI 定义中的写法
该模型的规范定义来自 Petstore 测试用 spec。在 fixtures/immutable/specifications/v2/petstorefake.yaml 中定义如下:
ArrayOfArrayOfNumberOnly:
type: object
properties:
ArrayArrayNumber:
type: array
items:
type: array
items:
type: number
同样的定义也出现在仓库的测试资源与 v3 版本中,例如 petstore-with-fake-endpoints-models-for-testing.yaml 和 petstore3fake.yaml,说明该模型同时覆盖了 Swagger 2.0 与 OpenAPI 3.0 两条规范的生成路径。
要点拆解:
- 外层
array:属性ArrayArrayNumber本身是一个数组; - 内层
array:items下又声明type: array,形成数组套数组; - 叶子元素
number:最内层元素类型为number,在 Java 端被映射为BigDecimal,以保证高精度数字不会因浮点运算而失真。
这种「嵌套数组」结构正是 ArrayOfArrayOfNumberOnly 命名的由来——它只包含一个 Array(数组)套 Array(数组)的 Number(数字)属性,用于隔离测试嵌套数组的生成逻辑。
生成源码逐行解析
swagger-codegen 根据上述规范,在 okhttp4-gson 模板下生成了 ArrayOfArrayOfNumberOnly.java。整类结构清晰,包含字段声明、链式 setter、惰性追加方法、标准 getter/setter 以及 equals/hashCode/toString 三个基础方法。
字段与 JSON 注解
@SerializedName("ArrayArrayNumber")
private List<List<BigDecimal>> arrayArrayNumber = null;
@SerializedName("ArrayArrayNumber")来自 Gson,将 Java 字段arrayArrayNumber与 JSON 中的键名ArrayArrayNumber一一对应,确保序列化与反序列化时字段名严格一致;- 泛型类型
List<List<BigDecimal>>与规范中的两层嵌套数组完全对应; - 默认值为
null,对应文档表格中的optional标注——未赋值时该字段不会影响 JSON 输出。
链式 setter 与追加方法
public ArrayOfArrayOfNumberOnly arrayArrayNumber(List<List<BigDecimal>> arrayArrayNumber) {
this.arrayArrayNumber = arrayArrayNumber;
return this;
}
public ArrayOfArrayOfNumberOnly addArrayArrayNumberItem(List<BigDecimal> arrayArrayNumberItem) {
if (this.arrayArrayNumber == null) {
this.arrayArrayNumber = new ArrayList<List<BigDecimal>>();
}
this.arrayArrayNumber.add(arrayArrayNumberItem);
return this;
}
- 第一个方法返回
this,支持链式调用风格:new ArrayOfArrayOfNumberOnly().arrayArrayNumber(list); addArrayArrayNumberItem(List<BigDecimal> item)是生成器为数组属性提供的追加方法,参数类型为内层数组元素类型List<BigDecimal>——注意追加的粒度是「一行数字列表」,而不是单个数字;- 追加方法采用惰性初始化:字段为
null时先创建ArrayList再add,避免空列表与 null 的语义混淆。
标准访问器与对象基础方法
public List<List<BigDecimal>> getArrayArrayNumber() { return arrayArrayNumber; }
public void setArrayArrayNumber(List<List<BigDecimal>> arrayArrayNumber) { this.arrayArrayNumber = arrayArrayNumber; }
equals、hashCode 均只基于 arrayArrayNumber 一个字段计算(对应 Objects.equals / Objects.hash),toString 使用 toIndentedString 对多行内容做 4 空格缩进,便于日志输出时可读。这些方法同样由模板统一生成,保证了所有模型类行为的一致性与可序列化性。
实际使用:构造与序列化一个二维数字列表
基于生成的 API,你可以这样构造并序列化 ArrayOfArrayOfNumberOnly:
import io.swagger.client.model.ArrayOfArrayOfNumberOnly;
import java.math.BigDecimal;
import java.util.Arrays;
import java.util.List;
ArrayOfArrayOfNumberOnly model = new ArrayOfArrayOfNumberOnly();
List<BigDecimal> row1 = Arrays.asList(new BigDecimal("1.1"), new BigDecimal("2.2"));
List<BigDecimal> row2 = Arrays.asList(new BigDecimal("3.3"));
model.addArrayArrayNumberItem(row1);
model.addArrayArrayNumberItem(row2);
此时 model 内部结构为 <a href="https://link.gitcode.com/i/97218de95d9a9ebea73688cd49e829e2" target="_blank">[1.1, 2.2], [3.3]]。当通过 okhttp4-gson 客户端自带的 [JSON.java(基于 Gson)序列化时,输出形如:
{
"ArrayArrayNumber": [
[1.1, 2.2],
[3.3]
]
}
值得注意的是,BigDecimal 由 Gson 原生支持,序列化时不会丢失精度;而字段的 @SerializedName("ArrayArrayNumber") 注解保证 JSON 键名与规范中的属性名保持一致,即使 Java 字段名采用驼峰命名也不影响线格式协议。
生成环境与库说明
该样例客户端由 okhttp4-gson 库模板生成。在 JavaClientCodegen.java 中,该库的官方描述为:
HTTP client: OkHttp 4.10.0. JSON processing: Gson 2.8.1. Enable Parcelable models on Android using
-DparcelableModel=true. Enable gzip request encoding using-DuseGzipFeature=true.
具体依赖版本可查看 okhttp4-gson 的 pom.xml:
| 组件 | 版本 |
|---|---|
| okhttp(含 logging-interceptor) | 4.10.0 |
| gson | 2.10.1 |
| gson-fire | 1.8.5 |
| swagger-annotations | 1.6.9 |
| Java 编译级别 | 1.7 |
其中的 gson-fire(GsonFire)在 JSON.java 中被用于注册 Animal 等继承体系的 TypeSelector 判别器,而 BigDecimal 则依赖 Gson 内置序列化能力,无需自定义 TypeAdapter——这也是嵌套数字数组得以透明序列化的原因。
关联阅读
- 模型总索引:okhttp4-gson 客户端 README,其中列出了包括
ArrayOfArrayOfNumberOnly在内的全部 36 个模型; - 同族模型:NumberOnly.md(单层
BigDecimal字段),可与本模型的嵌套数组字段对比理解生成差异; - 生成器原理:
okhttp4-gson库模板的注册与生成逻辑见 JavaClientCodegen.java; - 规范源头:嵌套数组定义见 petstorefake.yaml 与 petstore3fake.yaml。
通过本文对 ArrayOfArrayOfNumberOnly 的完整拆解可以看出:swagger-codegen 对 OpenAPI/Swagger 中「数组套数组」的声明,能够稳定地生成带完整方法链与序列化注解的 List<List<BigDecimal>> Java 字段。理解这一个模型的生成规律,即可举一反三地掌握生成器中所有嵌套容器类型(如数组套对象、Map 套数组)的输出模式。