swagger-codegen 生成的 Java 嵌套数组模型解析:以 ArrayOfArrayOfNumberOnly 为例

原创2026-10-10 16:16:06125 阅读
文章标签:开发工具代码生成API设计CLI

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——这也是嵌套数字数组得以透明序列化的原因。

关联阅读

通过本文对 ArrayOfArrayOfNumberOnly 的完整拆解可以看出:swagger-codegen 对 OpenAPI/Swagger 中「数组套数组」的声明,能够稳定地生成带完整方法链与序列化注解的 List<List<BigDecimal>> Java 字段。理解这一个模型的生成规律,即可举一反三地掌握生成器中所有嵌套容器类型(如数组套对象、Map 套数组)的输出模式。

登录后查看全文
swagger-codegen