Swagger Codegen 整型枚举模型深度解析：以 Java rest-assured 客户端中的 `Ints` 为例

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

本指南围绕自动生成的模型文档 samples/client/petstore/java/rest-assured/docs/Ints.md，结合同目录的生成源码与上游 OpenAPI 定义，完整讲解 Swagger Codegen 如何处理「整数型枚举」：从 OpenAPI 规格中的enum: [0,1,2,...]一路生成到 Java 枚举类、Gson TypeAdapter 以及模型文档。读完本文，你将掌握整数枚举的命名规律、getValue()/fromValue()的使用方式、JSON 序列化为数字而非字符串的底层机制，以及如何在 rest-assured 客户端中直接使用这类模型。

一、Ints.md是什么：一份由代码生成器产出的模型参考文档

在 Swagger Codegen 生成的所有客户端示例中，每个模型都会配套生成一份 Markdown 格式的参考文档，集中存放在<生成目录>/docs/下。Ints.md正是 Java rest-assured 客户端中Ints模型的标准 API 文档，其内容由生成器一次性产出，与模型源码一一对应：

• 文档：samples/client/petstore/java/rest-assured/docs/Ints.md
• 源码：samples/client/petstore/java/rest-assured/src/main/java/io/swagger/client/model/Ints.java

该文档主体是一个Enum列表，完整列出了 7 个枚举常量及其对应的整数值：

Ints.java头部的注释明确标注了这类文件的产生方式：

/* * NOTE: This class is auto generated by the swagger code generator program. * https://github.com/swagger-api/swagger-codegen.git * Do not edit the class manually. */

也就是说，docs/Ints.md与model/Ints.java一样，都是 Swagger Codegen 模板引擎的产物。手动修改它们会被下次重新生成覆盖，正确的做法是修改上游 OpenAPI 定义并重新生成。

二、源头追溯：OpenAPI 定义中的整数枚举

Ints模型并非凭空而来，它定义在 Petstore 的测试用规格文件中：fixtures/immutable/specifications/v2/petstorefake.yaml：

Ints: type: integer format: int32 description: True or False indicator enum: - 0 - 1 - 2 - 3 - 4 - 5 - 6

这段规格揭示了三个关键事实：

1. Ints是一个integer类型、int32格式的枚举，允许的取值被enum关键字限定为0~6；
2. 枚举值是数字而非字符串，这是它与字符串枚举（如常规的enum: [a, b, c]）最本质的区别，直接决定了后续 Java 代码的形态与 JSON 序列化行为；
3. description为 "True or False indicator"，这与同文件中Boolean模型的描述完全一致，属于规格文件测试数据的复用写法，不影响模型本身的语义。

从源码结构看，Swagger Codegen 对「类型 + enum 关键字」的模型会直接映射为 Java 枚举：字符串枚举生成String型枚举，而整数枚举生成Integer型枚举，Ints正是后者的典型样本。

三、源码级实现：Ints.java的完整结构

对照生成的 Ints.java，可以看到整数枚举的完整实现模式。

3.1 枚举常量与value字段

@JsonAdapter(Ints.Adapter.class) public enum Ints { NUMBER_0(0), NUMBER_1(1), NUMBER_2(2), NUMBER_3(3), NUMBER_4(4), NUMBER_5(5), NUMBER_6(6); private Integer value; Ints(Integer value) { this.value = value; }

每个常量通过构造函数绑定一个Integer值。注意类上的@JsonAdapter(Ints.Adapter.class)注解——它把 JSON 编解码逻辑委托给内嵌的Adapter，这是整数枚举能按数字而非字符串序列化的关键。

3.2 取值与转换方法

public Integer getValue() { return value; } @Override public String toString() { return String.valueOf(value); } public static Ints fromValue(String text) { for (Ints b : Ints.values()) { if (String.valueOf(b.value).equals(text)) { return b; } } return null; }

三个方法的语义非常清晰：

• getValue()：返回枚举对应的原始整数值，例如Ints.NUMBER_3.getValue()得到3；
• toString()：以字符串形式输出数值，如NUMBER_0输出"0"而不是常量名；
• fromValue(String text)：反向查找，将"5"这样的输入转换为NUMBER_5。注意：当输入不在枚举范围内时返回null而非抛异常，调用方需要自行判空。

3.3 Gson TypeAdapter：数字形态的 JSON 编解码

public static class Adapter extends TypeAdapter<Ints> { @Override public void write(final JsonWriter jsonWriter, final Ints enumeration) throws IOException { jsonWriter.value(enumeration.getValue()); } @Override public Ints read(final JsonReader jsonReader) throws IOException { Integer value = jsonReader.nextInt(); return Ints.fromValue(String.valueOf(value)); } }

Adapter继承自 Gson 的TypeAdapter<Ints>，实现了两个方向的处理：

• 序列化（write）：直接调用jsonWriter.value(枚举.getValue())，即把Ints.NUMBER_2写成 JSON 数字2；
• 反序列化（read）：用jsonReader.nextInt()读取 JSON 数字，再经fromValue映射回枚举常量。

这一实现从源码层面印证了「整数枚举在 JSON 中表现为裸数字」：{"someField": 3}合法，而{"someField": "3"}（带引号的字符串）不会被nextInt()接受。这与字符串枚举（序列化为带引号的字符串，如"available"）形成鲜明对比，是使用这类模型时最容易踩到的坑。

四、在 rest-assured 客户端中的实际使用

Ints位于包io.swagger.client.model下，是 rest-assured 示例工程的一部分（示例根目录：samples/client/petstore/java/rest-assured）。作为一个测试用模型，它的典型使用场景是模拟布尔语义的整数值字段，例如：

import io.swagger.client.model.Ints; // 取值 Integer v = Ints.NUMBER_4.getValue(); // v == 4 // 反向转换（输入不合法时返回 null） Ints fromText = Ints.fromValue("6"); // NUMBER_6 Ints invalid = Ints.fromValue("99"); // null，需判空 // 输出为数值字符串 String s = Ints.NUMBER_1.toString(); // "1"

当作为某个 API 请求/响应字段时，由于@JsonAdapter的存在，Gson 会自动完成枚举与 JSON 数字之间的双向转换，业务代码无需手写任何序列化逻辑——这也是docs/Ints.md只需列出枚举常量、无需额外说明的原因：编解码行为已经完全固化在模型自身中。

五、命名约定：为什么是NUMBER_0而不是VALUE_0

如果查看规格中的字符串枚举，会发现生成器通常采用VALUE_XXX或直接取原值转大写的命名。而Ints的常量名统一为NUMBER_<数字>，从源码结构和 Java 语言约束可以推断其动机：

• Java 枚举常量必须是合法标识符，不能以数字开头，因此裸的0、1无法作为常量名；
• 字符串枚举的值天然是合法标识符（如available可直接大写为AVAILABLE），而数字值必须引入前缀；
• 生成器统一选用NUMBER_前缀（NUMBER_0~NUMBER_6），形成与getValue()/fromValue()配套的、可预测的常量命名体系。

这一约定让docs/Ints.md中的常量名可以直接套用：看到NUMBER_3即可确定其 JSON 数值为3，无需翻阅任何额外资料。

六、文档与代码的同步关系

Ints.md不是手写维护的独立页面，而是生成流程的副产品。整套链路为：

1. 上游定义：petstorefake.yaml中声明Ints模型（type: integer+enum）；
2. 代码生成：Swagger Codegen 依据模型模板同时产出Ints.java与docs/Ints.md；
3. 交付使用：读者通过docs/Ints.md快速查阅枚举取值，通过Ints.java理解底层序列化实现。

因此，当 OpenAPI 规格中该模型的enum列表发生变化（例如新增取值7）时，重新生成后Ints.md的枚举表、Ints.java的常量与Adapter会同步更新，二者永远保持一致。对使用者而言，以docs/*.md为索引、以对应源码为实现依据，是阅读任何由 Swagger Codegen 生成的客户端代码库最有效的方法——Ints.md正是这套文档体系在「整数枚举」场景下的标准范例。

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