在使用 OpenAPI Generator 生成 Java 代码时，默认情况下，工具可能会自动调整模型字段的命名大小写，例如将 `AIOBCategory` 转换为 `aiOBCategory`。本教程将详细介绍如何通过配置 `identifierNamingConvention` 选项，将其设置为 `original`，从而确保生成的 Java 字段名称完全保留 OpenAPI 规范中定义的原始大小写格式，以满足特定的命名约定需求。
了解 OpenAPI Generator 的默认命名行为
OpenAPI Generator 是一款强大的工具，能够根据 OpenAPI 规范（YAML 或 JSON）自动生成客户端、服务器存根和模型。然而，在生成 Java 等面向对象语言的代码时，它通常会遵循目标语言的惯例。例如，对于 Java 字段，标准的做法是使用小驼峰命名法（camelCase）。这意味着，如果您的 OpenAPI 规范中定义了一个字段名为 AIOBCategory：
AIOBCategory: type: string maxLength: 100 example: ASD1234
在默认配置下，OpenAPI Generator 可能会将其转换为如下的 Java 字段：
@com.fasterxml.jackson.annotation.JsonProperty(JSON_PROPERTY_AI_O_B_CATEGORY) private java.lang.String aiOBCategory;
这种转换虽然符合 Java 的一般命名规范，但在某些特定场景下，例如需要严格匹配数据库字段名、集成遗留系统或遵循特殊的 API 契约时，我们可能希望保留 OpenAPI 规范中定义的原始大小写。
立即学习“Java免费学习笔记（深入）”；
精确控制字段命名：使用 identifierNamingConvention
OpenAPI Generator 提供了丰富的配置选项来定制生成过程，其中 identifierNamingConvention 就是用于控制标识符命名规则的关键选项。通过修改此选项，我们可以指定生成的字段、方法等标识符应遵循的命名约定。
要解决字段大小写被修改的问题，只需将 identifierNamingConvention 配置为 "original"。这将指示生成器完全保留 OpenAPI 规范中定义的原始字段名称，不做任何大小写转换。
Gradle 插件配置示例
如果您正在使用 org.openapitools.generator.gradle.plugin 插件来集成 OpenAPI Generator，可以通过 openApiGenerate 任务的 configOptions 块来设置 identifierNamingConvention。
以下是一个具体的 Gradle 配置示例，演示如何确保生成的 Java 字段保持原始大小写：
plugins {
id 'java'
id 'org.openapi.generator' version '7.x.x' // 请替换为实际版本，例如 '7.5.0'
}
// ... 其他项目配置 ...
openApiGenerate {
// 指定生成器名称，例如 "java" 或 "spring"
generatorName = "java"
// OpenAPI 规范文件的路径
inputSpec = "$rootDir/spec.yaml".toString()
// 生成代码的输出目录
outputDir = "$buildDir/generated-src/openapi".toString()
// 配置选项
configOptions = [
// 关键配置：将标识符命名约定设置为 "original"
identifierNamingConvention: "original"
// 您还可以添加其他配置，例如模型包名、API 包名等
// modelPackage: "com.example.api.model",
// apiPackage: "com.example.api.client"
]
// 确保生成前清理旧代码
clean = true
}
// 将生成的代码添加到项目的源集
sourceSets {
main {
java {
srcDir "$buildDir/generated-src/openapi/src/main/java"
}
}
}
// ... 其他任务或依赖 ...在上述配置中，identifierNamingConvention: "original" 是核心。一旦应用此配置并运行 Gradle 构建，之前被转换为 aiOBCategory 的字段，现在将精确地生成为 AIOBCategory：
// 假设 OpenAPI 规范中定义为 AIOBCategory @com.fasterxml.jackson.annotation.JsonProperty(JSON_PROPERTY_A_I_O_B_CATEGORY) private java.lang.String AIOBCategory;
注意事项：
- Jackson @JsonProperty 行为： 即使 Java 字段名通过 identifierNamingConvention: "original" 保持了原始大小写，@com.fasterxml.jackson.annotation.JsonProperty 注解中的值（如 JSON_PROPERTY_A_I_O_B_CATEGORY）可能仍然会遵循其内部的命名策略，将其转换为某种标准格式（如大写蛇形）。但这通常不影响 Java 字段本身的命名和 JSON 序列化/反序列化。
- 其他命名约定： identifierNamingConvention 除了 "original" 外，还支持其他值，例如 "snake_case"（蛇形命名）、"camelCase"（小驼峰命名，通常是默认值）、"PascalCase"（大驼峰命名）等。选择哪种约定取决于您的项目需求和团队规范。
- GeneratorName 的选择： 示例中使用了 java，但根据您的具体需求（如 Spring Boot 项目），您可能需要选择 spring、jaxrs-spec 等其他生成器。不同的生成器可能对某些配置项有特定的行为或默认值。
- 官方文档查阅： 强烈建议查阅 OpenAPI Generator 的官方配置文档（https://openapi-generator.tech/docs/configuration），以获取最全面和最新的配置选项信息，特别是针对您使用的特定生成器。
总结
通过在 OpenAPI Generator 配置中设置 identifierNamingConvention: "original"，您可以有效地控制 Java 代码生成过程中字段的命名大小写，确保其与 OpenAPI 规范中的定义完全一致。这对于维护命名一致性、简化与现有系统集成以及遵循特定编码标准至关重要。在应用此配置时，请务必结合项目实际需求和目标语言的通用实践进行权衡。
