swagger-codegen 生成模型 ArrayOfNumberOnly 详解：从 OpenAPI 数组定义到 okhttp4-gson 客户端 BigDecimal 列表

• 开发工具
• 代码生成
• API设计

导读

ArrayOfNumberOnly 是 swagger-codegen 基于 OpenAPI / Swagger 定义自动生成的一个纯数字数组模型：它在 OpenAPI 规范中只包含一个number类型的数组字段，在生成的 Java 客户端（okhttp4-gson）中对应一个List<BigDecimal>属性。本文以该模型为切片，完整讲解 Swagger/OpenAPI 二维数组定义如何被 swagger-codegen 解析、映射为 Java 泛型、生成模型文档与配套的序列化代码，并给出可直接运行的构建与集成方法。

模型文档原文速览

关联文档 ArrayOfNumberOnly.md 是生成客户端中每个模型都会自动产出的标准 API 参考页，核心内容如下：

从表格可见，swagger-codegen 生成的模型文档具有固定结构：Name（属性名）、Type（映射后的 Java 类型，并链接到对应类型的文档页）、Description（取自 OpenAPI 定义的描述字段）、Notes（标注可选性等约束）。该模型只有一个可选字段，因此Notes列标记为[optional]。

说明：BigDecimal.md为 swagger-codegen 运行时按需生成的链接目标，属于生成产物的一部分；同一 docs 目录下还存在 NumberOnly.md、ArrayOfArrayOfNumberOnly.md 等同类文档，可对照阅读。

OpenAPI 源定义：模型从何而来

ArrayOfNumberOnly 不是手写的 Java 类，而是由 swagger-codegen 从 OpenAPI 规范文件解析生成。其源定义位于测试桩规格 petstorefake.yaml：

ArrayOfNumberOnly: type: object properties: ArrayNumber: type: array items: type: number

逐行拆解这条定义：

• ArrayOfNumberOnly：模型名，最终成为 Java 类名ArrayOfNumberOnly；
• type: object：声明这是一个对象模型，对应生成 Java 类；
• ArrayNumber：属性名，对应 Java 字段arrayNumber（见下文命名规则）；
• type: array：声明该属性是数组；
• items.type: number：声明数组元素为number类型，在 Java 侧映射为BigDecimal。

同一规格文件中紧随其后还定义了 ArrayOfArrayOfNumberOnly，将items再嵌套一层type: array，用于验证二维数组（List<List<BigDecimal>>）的生成，两个模型共同覆盖了 swagger-codegen 对一维、二维数字数组的处理能力。

生成的 Java 模型：字段、泛型与 JSON 序列化

swagger-codegen 依据上述 YAML 生成了完整可编译的 Java 模型类 ArrayOfNumberOnly.java，其核心实现要点如下。

属性字段与 JSON 序列化注解

@SerializedName("ArrayNumber") private List<BigDecimal> arrayNumber = null;

• @SerializedName("ArrayNumber")：指定 JSON 序列化/反序列化时的字段名，严格保持与 OpenAPI 定义中的ArrayNumber一致，避免 Gson 默认驼峰转换导致字段名失配；
• 字段类型为List<BigDecimal>，即number数组元素映射为java.math.BigDecimal（okhttp4-gson 客户端使用 Gson 作为 JSON 库，见类头 import：com.google.gson.annotations.SerializedName、com.google.gson.TypeAdapter等）；
• 初始值为null，与文档中标注的[optional]语义一致——该字段可选，未赋值时 JSON 中不输出该键。

链式 setter 与追加方法

模型类为字段同时提供两种写入方式：

public ArrayOfNumberOnly arrayNumber(List<BigDecimal> arrayNumber) { this.arrayNumber = arrayNumber; return this; } public ArrayOfNumberOnly addArrayNumberItem(BigDecimal arrayNumberItem) { if (this.arrayNumber == null) { this.arrayNumber = new ArrayList<BigDecimal>(); } this.arrayNumber.add(arrayNumberItem); return this; }

• arrayNumber(...)返回this，支持链式调用（fluent API），方便一行内完成模型构建；
• addArrayNumberItem(...)负责懒初始化ArrayList后逐个追加元素，适合以流式方式向数组填充数据。

取值方法、equals/hashCode 与 toString

public List<BigDecimal> getArrayNumber() { return arrayNumber; } public void setArrayNumber(List<BigDecimal> arrayNumber) { this.arrayNumber = arrayNumber; }

• getArrayNumber()标注了@ApiModelProperty(value = "")，是 swagger-annotations 在生成模型上附加的自描述注解；
• equals/hashCode基于Objects.equals/Objects.hash仅比较arrayNumber字段，便于断言与集合操作；
• toString()输出class ArrayOfNumberOnly { arrayNumber: ... }格式，配合私有toIndentedString对多行字符串做 4 空格缩进，保证日志可读性。

类型映射规则：number → BigDecimal

该模型的关键映射关系是 OpenAPInumber类型到 JavaBigDecimal。这一映射由 swagger-codegen 的类型解析机制决定，可以从以下角度理解：

• BigDecimal提供任意精度的十进制运算，适合承载 OpenAPI 规范中未限定整数/浮点边界的number类型，避免浮点精度丢失；
• 数组维度直接体现为 Java 泛型嵌套：一维array映射为List<BigDecimal>，二维array映射为List<List<BigDecimal>>（对应 ArrayOfArrayOfNumberOnly.java）；
• 若 OpenAPI 定义为integer类型，则通常映射为Integer/Long，number与integer在 Java 侧分属不同映射分支。

在 okhttp4-gson 客户端中，BigDecimal的序列化由 Gson 内置处理；模型类头部引用的JsonAdapter、TypeAdapter、JsonReader/JsonWriter（com.google.gson.stream包）表明该生成器还具备为特殊类型输出自定义 TypeAdapter 的能力，BigDecimal这类标准类型则走 Gson 默认适配。

构建、运行与集成实践

编译生成客户端

ArrayOfNumberOnly 所在的 okhttp4-gson 客户端是标准 Maven 工程，仓库根目录pom.xml为多模块父 POM，客户端自身的构建文件位于 samples/client/petstore/java/okhttp4-gson/pom.xml，同时提供 Gradle 包装器（gradlew/gradlew.bat）与 gradle.properties。典型构建方式：

mvn compile # 或使用仓库自带的 Gradle 包装器 ./gradlew build

构建产物会包含io.swagger.client.model.ArrayOfNumberOnly类，可直接作为依赖加入业务工程。

在代码中使用 ArrayOfNumberOnly

结合上文 API，一段可运行的使用示例：

import io.swagger.client.model.ArrayOfNumberOnly; import java.math.BigDecimal; ArrayOfNumberOnly model = new ArrayOfNumberOnly() .addArrayNumberItem(new BigDecimal("3.14159")) .addArrayNumberItem(new BigDecimal("2.71828")); // 读取整个列表 List<BigDecimal> numbers = model.getArrayNumber();

若需一次性整体赋值：

List<BigDecimal> list = new ArrayList<>(); list.add(new BigDecimal("100.5")); model.setArrayNumber(list);

关联的测试用例

虽然本客户端测试目录中暂无针对 ArrayOfNumberOnly 的独立测试，但 FakeApiTest.java 中大量使用了BigDecimal参数（如fakeOuterNumberSerialize、fakeOuterNumber等接口调用），验证了该客户端对BigDecimal编解码的整体可用性，可作为number类型在请求/响应链路上正确工作的佐证。

与同级模型文档的关系

生成文档目录 samples/client/petstore/java/okhttp4-gson/docs 下每个模型对应一份同名.md文档，结构完全一致。与 ArrayOfNumberOnly 相关度最高的两份为：

• NumberOnly.md：单个number字段模型，对应源定义中的NumberOnly（properties.JustNumber: type: number），帮助理解"单数字"与"数字数组"在文档与代码两端的差异；
• ArrayOfArrayOfNumberOnly.md：二维数字数组模型，属性类型为List<List<BigDecimal>>，与本文模型互为嵌套对照，构成 swagger-codegen 处理数字数组的完整样例链。

这三份文档连同对应源码（ArrayOfNumberOnly.java、ArrayOfArrayOfNumberOnly.java）一起，可以作为学习 swagger-codegen 模型生成机制的最小闭环示例。

小结

ArrayOfNumberOnly 虽是一个仅含单个可选数组字段的简单模型，却完整串联了 swagger-codegen 的整条生成链路：OpenAPI 源定义（type: array+items.type: number）→ 类型解析（number→BigDecimal）→ Java 模型生成（字段、链式 setter、Gson 注解、equals/toString）→ 模型文档自动生成（属性表 + 类型链接）。理解这一链路后，任何包含数字数组（或嵌套数字数组）字段的 OpenAPI 模型，都能在阅读生成文档的同时，在源码中准确预测其字段名、泛型类型与可用 API 形态。

• 开发工具
• 代码生成
• API设计