swagger-codegen 生成嵌套数组模型解析:以 ArrayOfArrayOfNumberOnly 为例深入 List<List<BigDecimal>>

原创2026-09-23 20:01:271,769 阅读
文章标签:开发工具代码生成API设计CLI

swagger-codegen 生成嵌套数组模型解析:以 ArrayOfArrayOfNumberOnly 为例深入 List<List<BigDecimal>>

导读

本文聚焦 swagger-codegen 在生成 Java(Jersey1)客户端时,如何处理 OpenAPI / Swagger 定义中的嵌套数组(二维数组)模型。以自动生成的模型文档 ArrayOfArrayOfNumberOnly.md 为起点,沿着"文档属性表 → 源 YAML 定义 → 生成后的 POJO 源码"的完整链路,剖析 arrayArrayNumber: List<List<BigDecimal>> 这一类型如何从规范描述一步步落地为可调用的 Java 代码。读完本文,你将掌握阅读任意 swagger-codegen 生成模型文档的方法,并理解嵌套集合类型在生成产物中的形态与用法。

一、这份模型文档是什么

在 swagger-codegen 生成的客户端工程中,每个模型(Model)都会对应一份独立的 Markdown 文档,位于生成的 docs/ 目录下。本文讨论的 ArrayOfArrayOfNumberOnly.md 是 Jersey1 客户端示例工程中为 ArrayOfArrayOfNumberOnly 模型自动生成的技术参考页,全文是一张标准的属性表:

属性名 类型 描述 备注
arrayArrayNumber List<List<BigDecimal>> — 可选(optional)

这张表虽然只有一行,但承载了三条关键信息:

  1. 模型名:ArrayOfArrayOfNumberOnly——即"仅包含一个数组的数组"的模型,专门用于测试生成器对深层嵌套集合类型的处理;
  2. 属性名与 Java 类型映射:arrayArrayNumber 被生成为 List<List<BigDecimal>>,外层列表的每个元素又是一个 List<BigDecimal>;
  3. 可选性:该属性标注为 [optional],意味着在 JSON 中它可以缺失,对应到源码中初始值为 null。

类似地,同一目录下的 ArrayOfNumberOnly.md 展示了一维版本 arrayNumber: List<BigDecimal>,二者对照即可清晰看出 swagger-codegen 对"一层数组"与"两层嵌套数组"的类型推导差异。

二、源定义:OpenAPI 中的嵌套数组声明

生成的文档并非凭空而来,它忠实反映了输入规范中的模型定义。在仓库的测试规范(fixtures)中可以找到该模型的原始声明。

Swagger 2.0(v2)版本

在 petstorefake.yaml 中定义如下:

ArrayOfArrayOfNumberOnly:
  type: object
  properties:
    ArrayArrayNumber:
      type: array
      items:
        type: array
        items:
          type: number

关键点在于 items 的递归嵌套:ArrayArrayNumber 本身是数组,其 items 又是数组,最内层才是 type: number。这正是二维数组在 OpenAPI 2.0 中的标准表达方式。

OpenAPI 3.0(v3)版本

同一模型也出现在 v3 测试规范 petstore3fake.yaml 中,结构完全一致:

ArrayOfArrayOfNumberOnly:
  type: object
  properties:
    ArrayArrayNumber:
      type: array
      items:
        type: array
        items:
          type: number

两个版本的规范(v2 petstorefake.yaml 与 v3 petstore3fake.yaml)都被用于生成样本,验证 swagger-codegen 对 2.0/3.0 两种规范格式的嵌套数组解析一致性。另外,samplesServers.yaml 与 petstoreMixed3.yaml 也引用了该模型用于其他生成场景。

从代码生成器的角度看,items 层数决定了最终泛型的嵌套深度:每多一层 items,生成的集合泛型就多包一层 List<>。

三、生成结果:Jersey1 客户端中的 POJO 实现

在 Jersey1 示例工程中,该模型被生成到 ArrayOfArrayOfNumberOnly.java,位于包 io.swagger.client.model 下。生成后的类是一个典型的 Java Bean(POJO),其字段声明精确对应文档中的类型:

@JsonProperty("ArrayArrayNumber")
private List<List<BigDecimal>> arrayArrayNumber = null;

注意这里有两个值得留意的细节:

  1. JSON 字段名保留了大写:源 YAML 中属性名是 ArrayArrayNumber(首字母大写),生成器将其保留为 @JsonProperty("ArrayArrayNumber"),而 Java 字段名则被规范化为驼峰小写 arrayArrayNumber。这意味着序列化/反序列化时 JSON 键严格使用 "ArrayArrayNumber",与文档表中展示的属性名(小写形式)存在大小写差异——阅读生成文档时应以 @JsonProperty 注解为准。

  2. 数值类型映射为 BigDecimal:最内层 type: number 被映射为 java.math.BigDecimal,这是 swagger-codegen 在 Java 客户端中处理浮点/高精度数值的默认策略,可避免 double 的精度丢失。

生成的方法集

除了字段与 getter/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;
}
  • arrayArrayNumber(...):流式设置器,返回 this,支持链式调用,是生成器为简化构建代码而添加的惯例方法;
  • addArrayArrayNumberItem(...):单项追加器,在字段为 null 时先惰性初始化 ArrayList 再追加,避免调用方手动判空。这也是为什么文档中该属性标注 [optional] 时,源码初始值保持 null、由追加方法兜底的原因。

此外,类中还自动生成了基于 Objects.equals/Objects.hash 的 equals()、hashCode(),以及格式化输出的 toString()(通过私有 toIndentedString 实现 4 空格缩进),保证模型可以直接用于断言比较和日志打印。

四、一维与二维:与 ArrayOfNumberOnly 的对比

将 ArrayOfNumberOnly.md 与本模型并列,可以直观看出集合层数对生成类型的影响:

模型 源定义 items 层数 生成类型
ArrayOfNumberOnly 1 层(array → number) List<BigDecimal>
ArrayOfArrayOfNumberOnly 2 层(array → array → number) List<List<BigDecimal>>

从源码结构看,swagger-codegen 的代码生成模板会依据规范中 items 的递归深度逐层展开泛型;只要规范里继续嵌套 items,生成类型就会相应扩展为 List<List<List<...>>>。这两个模型被同时收录在 petstore fake 规范中,本身就是为覆盖此类"嵌套集合类型推导"场景而设计的测试用例。

五、实际使用:构建与读写嵌套数组

基于生成后的 POJO,调用方可以这样构造一个 ArrayOfArrayOfNumberOnly 对象:

ArrayOfArrayOfNumberOnly model = new ArrayOfArrayOfNumberOnly()
    .addArrayArrayNumberItem(Arrays.asList(new BigDecimal("1.1"), new BigDecimal("2.2")))
    .addArrayArrayNumberItem(Arrays.asList(new BigDecimal("3.3")));

配合 Jersey1 客户端生成的 JSON 处理代码(该工程默认使用 Jackson + @JsonProperty 注解),上述对象序列化后的 JSON 大致为:

{
  "ArrayArrayNumber": [
    [1.1, 2.2],
    [3.3]
  ]
}

读取时同样按两层列表遍历即可:

for (List<BigDecimal> row : model.getArrayArrayNumber()) {
  for (BigDecimal value : row) {
    // 处理每个数值
  }
}

由于字段默认值为 null(对应 [optional]),读取前建议先判空,或依赖 addArrayArrayNumberItem 的惰性初始化来规避空指针。

六、如何在自己的项目中复现与验证

如果你想在本地复现这份文档与代码的生成过程,仓库提供了完整的样本与规范:

  1. 输入规范:使用 petstorefake.yaml(Swagger 2.0)或 petstore3fake.yaml(OpenAPI 3.0),其中都包含 ArrayOfArrayOfNumberOnly 模型;
  2. 生成目标:选择 Java 客户端的 jersey1 生成器;
  3. 生成命令:通过仓库根目录的 pom.xml 构建出 CLI 后,使用 java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i <规范路径> -l java -c <配置>(配置示例可参考 java-client.xml)执行生成;
  4. 校验产物:生成后检查输出工程中的 src/main/java/io/swagger/client/model/ArrayOfArrayOfNumberOnly.java 与 docs/ArrayOfArrayOfNumberOnly.md,应与仓库 samples/client/petstore/java/jersey1 目录下的现有产物一致。

小结

通过 ArrayOfArrayOfNumberOnly 这一个模型,我们可以完整观察到 swagger-codegen 处理嵌套数组的三层映射关系:OpenAPI 规范中的递归 items 声明 → 生成文档属性表中的 List<List<BigDecimal>> → Java POJO 中的泛型字段与便捷方法。这份模型文档虽然只有一张属性表,却是理解生成器类型推导、JSON 字段命名规则与集合便捷方法设计的绝佳切片。后续阅读其他生成模型文档(如 Pet.md、Order.md)时,都可以沿用本文的"文档表 → 源定义 → 生成源码"三步分析法。

登录后查看全文
swagger-codegen