理解 Swagger Codegen 的大小写命名转换：以 Java okhttp-gson 客户端 `Capitalization` 模型为例

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

在通过 Swagger/OpenAPI 定义自动生成多语言客户端与服务端代码时，属性命名的大小写处理（camelCase、PascalCase、snake_case 等）是最容易产生困惑的环节：原始 spec 中的smallCamel、small_Snake、SCA_ETH_Flow_Points这类混合风格字段，在生成代码后如何映射为语言惯用的命名？本文以 swagger-codegen 仓库中 Java okhttp-gson 客户端示例的Capitalization模型文档为切入点，完整解读该模型的全部字段定义、生成后的 Java 代码结构、JSON 序列化映射关系，以及它是如何用于验证代码生成器命名转换规则的，帮助你在设计 OpenAPI 规范时规避大小写命名陷阱。

Capitalization模型的来源与定位

Capitalization并不是某个真实业务对象，而是 swagger-codegen 项目专门为测试大小写转换逻辑而设计的"假模型"（fake model）。它定义在 Petstore 测试规范modules/swagger-codegen/src/test/resources/2_0/petstore-with-fake-endpoints-models-for-testing.yaml中，该规范明确声明"主要用于测试 Petstore 服务端及假端点、假模型，请勿用于其他目的"。

在该 YAML 的definitions段中，Capitalization的定义如下：

Capitalization: type: object properties: smallCamel: type: string CapitalCamel: type: string small_Snake: type: string Capital_Snake: type: string SCA_ETH_Flow_Points: type: string ATT_NAME: description: > Name of the pet type: string

可以看出，这个模型刻意把小驼峰、大驼峰、小写蛇形、大写蛇形、混合分隔符、全大写常量等六种命名风格混在一个对象里，目的就是验证代码生成器在不同语言下对每种命名风格的处理行为。

模型属性总览：文档中的核心表格

目标文档samples/client/petstore/java/okhttp-gson/docs/Capitalization.md以表格形式完整列出了该模型的六个属性，这是所有生成语言共享的"模型契约"：

各属性的原始 spec 名称与生成后 Java 属性名的对应关系如下：

其中scAETHFlowPoints是最值得注意的边界案例：SCA_ETH_Flow_Points经过 camelCase 化后并未变成直觉上的scaEthFlowPoints，而是被转换成scAETHFlowPoints（AETH三个字母被保留为大写），这正是代码生成器在处理连续大写缩写时的具体行为，从生成的 Java 类中可以精确验证这一点。

Java 生成代码的完整结构

Capitalization模型在 Java okhttp-gson 客户端中被生成为 Capitalization.java，完整展示了 Swagger Codegen 为每个模型类生成的标准结构。

字段声明与 JSON 序列化注解

public class Capitalization { @SerializedName("smallCamel") private String smallCamel = null; @SerializedName("CapitalCamel") private String capitalCamel = null; @SerializedName("small_Snake") private String smallSnake = null; @SerializedName("Capital_Snake") private String capitalSnake = null; @SerializedName("SCA_ETH_Flow_Points") private String scAETHFlowPoints = null; @SerializedName("ATT_NAME") private String ATT_NAME = null; ... }

关键点在于：@SerializedName中始终保留 spec 中的原始属性名，而 Java 字段名则统一为 camelCase。这意味着序列化/反序列化时，JSON 键与 spec 完全一致（如"Capital_Snake"），而代码内访问使用 Java 风格命名——两者的对应关系由 Gson 的@SerializedName注解维护。这也是"与 OpenAPI 定义保持线上协议不变、同时让生成代码符合语言惯例"这一设计目标的直接体现。

链式 setter 与 getter

每个属性都生成一套标准的三件套：链式 setter、getter 与 plain setter。以capitalCamel为例：

public Capitalization capitalCamel(String capitalCamel) { this.capitalCamel = capitalCamel; return this; } /** * Get capitalCamel * @return capitalCamel **/ @ApiModelProperty(value = "") public String getCapitalCamel() { return capitalCamel; } public void setCapitalCamel(String capitalCamel) { this.capitalCamel = capitalCamel; }

链式 setter 返回Capitalization自身，支持new Capitalization().smallCamel("x").capitalCamel("y")式的流式构造；getter 上标注@ApiModelProperty，把description（如ATT_NAME的 "Name of the pet"）作为 Swagger 注解的value一并生成。

equals、hashCode 与 toString

生成类还自动实现了对象协议三方法：

• equals使用Objects.equals对六个字段逐一比较；
• hashCode通过Objects.hash(smallCamel, capitalCamel, smallSnake, capitalSnake, scAETHFlowPoints, ATT_NAME)计算；
• toString以class Capitalization { ... }的缩进格式输出全部字段（内部通过私有方法toIndentedString处理多行字符串的缩进）。

这些方法为集合去重、日志输出、单元测试断言提供了基础能力。

命名转换在不同语言中的落地差异

同一个 spec 模型，在不同语言的生成结果中会呈现不同的命名习惯。这正是Capitalization模型作为测试夹具的核心价值——验证同一套命名规则在各语言生成器中的一致性。

C#（PascalCase 属性）

在 Capitalization.cs 中，属性名被生成为 C# 惯例的 PascalCase（SmallCamel、CapitalCamel、SmallSnake、CapitalSnake、SCAETHFlowPoints、ATT_NAME），而[DataMember(Name="small_Snake", ...)]同样保留原始 JSON 键名：

[DataMember(Name="small_Snake", EmitDefaultValue=false)] public string SmallSnake { get; set; } [DataMember(Name="SCA_ETH_Flow_Points", EmitDefaultValue=false)] public string SCAETHFlowPoints { get; set; } [DataMember(Name="ATT_NAME", EmitDefaultValue=false)] public string ATT_NAME { get; set; }

注意SCA_ETH_Flow_Points在 C# 中变成了SCAETHFlowPoints，与 Java 的scAETHFlowPoints又略有不同——这说明不同语言生成器对连续大写缩写的拆分策略并不完全相同。

JavaScript（prototype 属性）

在 Capitalization.js 中，通过constructFromObject从普通对象反序列化：

if (data.hasOwnProperty('smallCamel')) obj.smallCamel = ApiClient.convertToType(data['smallCamel'], 'String'); if (data.hasOwnProperty('SCA_ETH_Flow_Points')) obj.sCAETHFlowPoints = ApiClient.convertToType(data['SCA_ETH_Flow_Points'], 'String'); if (data.hasOwnProperty('ATT_NAME')) obj.ATT_NAME = ApiClient.convertToType(data['ATT_NAME'], 'String');

这里再次出现"读取SCA_ETH_Flow_Points、写入sCAETHFlowPoints"的对应关系，进一步印证了该特殊映射是跨语言通用的生成行为，而非 Java 特有的实现细节。

测试夹具：命名规则的可验证证据

仓库为该模型生成了各语言的测试骨架，例如 C# 的 CapitalizationTests.cs 使用 NUnit 为每个属性生成独立测试方法（SmallCamelTest、CapitalCamelTest、SmallSnakeTest、CapitalSnakeTest、SCAETHFlowPointsTest、ATT_NAMETest），测试方法名同样遵循目标语言的命名风格，作为开发者补全单元测试的起点模板。

此外，Capitalization模型出现在仓库的多个生成示例中，覆盖 Java（okhttp-gson、jersey2、retrofit2、resttemplate、rest-assured、feign 等）、C#、Go、JavaScript、Python、Ruby、PHP、Perl、Swift 等几乎所有支持的客户端与部分服务端生成器（如 jaxrs-cxf 服务端示例），并且在 okhttp-gson 客户端 README 的 Models 索引中与AdditionalPropertiesClass、Animal等并列列出。这一横跨全语言生成器的存在，说明命名转换规则是 swagger-codegen 模板引擎的核心能力之一，而Capitalization正是检验该能力的标准化试金石。

对 API 设计者的实践建议

结合Capitalization模型的验证结果，在编写 OpenAPI/Swagger 定义时可以得出以下可操作经验：

1. 属性命名要遵循单一风格：spec 中混用smallCamel、small_Snake、SCA_ETH_Flow_Points会导致不同语言生成出形态各异的代码，增加阅读与调试成本。建议全篇统一使用小驼峰或 snake_case。
2. 全大写常量名会被保留：如ATT_NAME在 Java 中保持ATT_NAME原样，但在 getter 处被生成为getATTNAME()（源码第 150 行），这种"字段名与 getter 名不一致"的情况容易引起困惑，应尽量避免使用此类命名。
3. 连续大写缩写是高风险区：SCA_ETH_Flow_Points→scAETHFlowPoints/SCAETHFlowPoints的映射在不同语言间存在差异，说明连续大写缩写（如SCA、ETH）的转换规则并无跨语言统一标准，设计时应尽量避免。
4. 线上 JSON 键名不会变：无论生成代码的字段名如何转换，@SerializedName/[DataMember(Name=...)]保证线上协议的键名始终与 spec 一致，因此改动生成代码命名不会破坏已有的 API 契约——这既是兼容性保证，也意味着你在 spec 里写什么键名，客户端就会以什么键名收发 JSON。

小结

Capitalization模型虽然只是一个用于测试的"假模型"，却是理解 swagger-codegen 命名转换机制的最佳标本。通过 模型文档、Java 生成源码 与 原始 YAML 定义 三者的对照，你可以完整掌握：原始属性名如何被 camelCase 化、特殊缩写如何处理、JSON 键名如何被保留，以及同一规则在不同语言生成器中的差异化落地。这对设计规范、排查生成代码、二次开发模板引擎都有直接的参考价值。

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