本文旨在解决OpenAPI Generator在生成Java代码时，模型字段命名不符合预期（如自动转换为驼峰命名）的问题。通过详细阐述`identifierNamingConvention`配置项，并提供Gradle插件的示例代码，指导开发者如何将生成字段的命名规范调整为与OpenAPI规范中定义的原始名称保持一致，从而确保代码风格的统一性和可预测性。
1. 理解 OpenAPI Generator 的字段命名转换机制
OpenAPI Generator 是一款强大的工具，能够根据 OpenAPI 规范（YAML 或 JSON）自动生成各种语言的客户端、服务器端代码和文档。在生成 Java 代码时，尤其是在处理数据模型（DTOs）时，它通常会根据语言的最佳实践和约定，对字段名进行自动转换。
例如，一个在 OpenAPI 规范中定义为 AIOBCategory 的字段：
AIOBCategory: type: string maxLength: 100 example: ASD1234
在默认情况下，OpenAPI Generator 可能会将其转换为 Java 代码中的小驼峰命名（camelCase），并在其上方添加 Jackson 注解：
立即学习“Java免费学习笔记（深入）”；
@com.fasterxml.jackson.annotation.JsonProperty(JSON_PROPERTY_AI_O_B_CATEGORY) private java.lang.String aiOBCategory;
这种自动转换在某些情况下是期望的行为，但在另一些场景下，开发者可能希望生成的字段名能严格保持与 OpenAPI 规范中定义的一致，即 AIOBCategory。
2. 解决方案：配置 identifierNamingConvention
OpenAPI Generator 提供了丰富的配置选项来控制代码生成的各个方面，其中 identifierNamingConvention 是用于控制标识符（包括字段名、方法名等）命名规范的关键选项。通过修改此配置，我们可以指定生成字段的命名方式。
2.1 核心配置项
要保持字段命名与 OpenAPI 规范中定义的原样一致，我们需要将 identifierNamingConvention 设置为 "original"。
2.2 Gradle 插件配置示例
如果您的项目使用 Gradle 构建，并通过 org.openapitools.generator.gradle.plugin 插件来集成 OpenAPI Generator，您可以在 build.gradle 文件中这样配置：
plugins {
id "org.openapi.generator" version "6.6.0" // 使用您项目实际的插件版本
}
openApiGenerate {
// 指定生成器名称，例如 "java" 或 "spring"
generatorName = "java"
// 输入的 OpenAPI 规范文件路径
inputSpec = "$rootDir/spec.yaml".toString()
// 生成代码的输出目录
outputDir = "$buildDir/generated-src/main/java".toString()
// 清理输出目录
cleanOutput = true
// 关键配置：通过 configOptions 设置 identifierNamingConvention
configOptions = [
// 将 identifierNamingConvention 设置为 "original"
// 这将确保生成的字段名与 OpenAPI 规范中定义的名称完全一致
identifierNamingConvention: "original",
// 其他可能的配置，例如：
// library: "spring-boot", // 如果使用 Spring Boot 生成器
// dateLibrary: "java8",
// modelPackage: "com.example.api.model"
]
}配置说明：
- generatorName: 指定您要使用的代码生成器，例如 java、spring、typescript-angular 等。
- inputSpec: 指向您的 OpenAPI 规范文件（YAML 或 JSON）。
- outputDir: 指定生成代码的输出目录。
- configOptions: 这是一个 Map 结构，用于传递特定的生成器配置选项。在这里，我们将 identifierNamingConvention 设置为 "original"。
2.3 预期生成结果
经过上述配置后，当您再次运行 OpenAPI Generator 时，之前提到的 AIOBCategory 字段将按期望生成：
// 注意：JsonProperty 注解的常量名可能仍会根据内部逻辑转换， // 但私有字段名将保持与 OpenAPI 规范一致。 @com.fasterxml.jackson.annotation.JsonProperty(JSON_PROPERTY_AI_O_B_CATEGORY) private java.lang.String AIOBCategory;
3. identifierNamingConvention 的其他值
除了 "original"，identifierNamingConvention 还支持其他常用的命名规范，以适应不同的项目需求和编码风格：
- camelCase (默认值): 小驼峰命名，例如 aiObCategory。
- PascalCase: 大驼峰命名，例如 AiObCategory。
- snake_case: 下划线命名，例如 ai_ob_category。
- kebab-case: 短横线命名，例如 ai-ob-category。
- NONE: 不进行任何转换，与 original 类似，但可能在某些边缘情况下有细微差别。
根据您的项目规范和团队约定，选择最合适的命名约定。
4. 注意事项与最佳实践
- 版本兼容性： 确保您使用的 OpenAPI Generator 插件版本支持 identifierNamingConvention 配置项。虽然这是一个相对稳定的功能，但查阅您所用版本的官方文档总是明智之举。
- 全局与局部： identifierNamingConvention 是一个全局设置，会影响所有生成的标识符。如果您只需要对特定字段进行特殊处理，可能需要考虑在 OpenAPI 规范中使用 x- 扩展属性，或者在生成后进行后处理。
- Jackson 注解： 即使字段名保持了 original，Jackson 的 @JsonProperty 注解仍然可能根据其内部逻辑生成，以确保 JSON 序列化和反序列化的正确性。通常情况下，这不会影响您的业务逻辑。
- 文档查阅： 对于更深入的配置和高级用法，请务必参考 OpenAPI Generator 的官方文档：https://www.php.cn/link/8d31e1ca580336797fc5c552cc86b96b。
总结
通过简单地在 configOptions 中设置 identifierNamingConvention: "original"，开发者可以有效地控制 OpenAPI Generator 生成 Java 代码时字段的命名规范，使其与 OpenAPI 规范中的定义保持一致。这有助于维护代码风格的统一性，减少因自动转换而导致的意外行为，并提高代码的可读性和可维护性。理解并灵活运用 identifierNamingConvention 配置项，是高效使用 OpenAPI Generator 的关键一环。
