本文旨在指导如何通过OpenAPI Generator的配置选项，精确控制Java代码生成过程中模型字段的命名规范，特别是在保留原始定义大小写方面。通过调整`identifierNamingConvention`参数为`original`，开发者可以确保生成的Java字段与OpenAPI规范中定义的名称保持一致，避免默认的驼峰命名转换，从而满足特定的编码风格或兼容性需求。
引言：OpenAPI Generator与字段命名挑战
在使用org.openapitools.generator.gradle.plugin.tasks.GenerateTask等工具基于YAML或JSON格式的OpenAPI规范生成Java代码时，开发者可能会遇到一个常见的挑战：生成的Java模型字段的命名方式与OpenAPI规范中定义的原始字段名不一致。例如，一个在OpenAPI规范中定义为AIOBCategory的字段，在默认情况下可能被生成为aiOBCategory。这种自动的命名转换（通常是转换为小驼峰命名）虽然符合Java的常见编码规范，但在某些特定场景下，如需要严格保持与外部系统接口字段名的一致性，或者遵循特定的领域命名规范时，这种转换可能并不理想。
解决方案：identifierNamingConvention配置选项
OpenAPI Generator提供了丰富的配置选项，允许开发者精细化控制代码生成的各个方面，其中就包括字段的命名规范。解决上述问题的关键在于利用configOptions中的identifierNamingConvention参数。
1. identifierNamingConvention的作用
identifierNamingConvention配置选项用于指定在生成代码时，如何转换OpenAPI规范中的标识符（如字段名、操作ID等）。它支持多种命名约定，包括：
立即学习“Java免费学习笔记（深入）”；
- camelCase (默认值，小驼峰命名)
- snake_case (蛇形命名)
- PascalCase (大驼峰命名)
- kebab-case (烤串命名)
- original (保留原始命名)
对于需要保持字段原始大小写的情况，将identifierNamingConvention设置为original是最佳选择。
2. 配置示例：Gradle插件
以下是一个使用Gradle插件配置OpenAPI Generator以保留原始字段大小写的示例：
假设OpenAPI规范中定义了一个模型字段如下：
AIOBCategory: type: string maxLength: 100 example: ASD1234
默认情况下，生成的Java代码可能如下所示：
@com.fasterxml.jackson.annotation.JsonProperty(JSON_PROPERTY_AI_O_B_CATEGORY) private java.lang.String aiOBCategory;
为了使其生成为private java.lang.String AIOBCategory;，您需要在build.gradle文件中进行如下配置：
openApiGenerate {
// 指定生成器名称，例如 "spring" 或 "java"
generatorName = "spring"
// OpenAPI规范文件的路径
inputSpec = "$rootDir/spec.yaml".toString()
// 生成代码的输出目录
outputDir = "$buildDir/generated-sources/openapi".toString()
// 配置选项
configOptions = [
// 关键配置：将标识符命名约定设置为 "original"
identifierNamingConvention: "original"
]
// 其他可选配置，例如包名、模型名后缀等
apiPackage = "com.example.api"
modelPackage = "com.example.model"
// ...
}配置说明：
- openApiGenerate：这是OpenAPI Generator Gradle插件的主要配置块。
- generatorName：指定要使用的代码生成器。例如，"spring"用于生成Spring Boot相关的代码，"java"用于生成纯Java客户端等。
- inputSpec：指向您的OpenAPI规范（YAML或JSON文件）的路径。
- outputDir：指定生成代码的输出目录。
- configOptions：这是一个映射（Map），用于传递各种自定义配置选项给生成器。
- identifierNamingConvention: "original"：这是核心配置。它指示生成器在处理字段名、方法名等标识符时，应尽可能保留其在OpenAPI规范中定义的原始大小写和格式。
应用上述配置后，当您再次运行Gradle的生成任务时，AIOBCategory字段将按照您的预期生成：
@com.fasterxml.jackson.annotation.JsonProperty(JSON_PROPERTY_A_I_O_B_CATEGORY) // 注意：JsonProperty名称可能仍会进行一些转换以符合Java常量命名规范 private java.lang.String AIOBCategory;
3. 注意事项
- JsonProperty的命名： 即使字段名被保留为AIOBCategory，@JsonProperty注解中的常量名（如JSON_PROPERTY_A_I_O_B_CATEGORY）仍可能遵循Java的常量命名规范（大写蛇形）。这是正常行为，因为它是一个内部常量，不影响字段本身的名称。
- 生成器兼容性： 大多数官方维护的生成器都支持identifierNamingConvention选项。如果您使用的是自定义或社区维护的生成器，请查阅其文档以确认支持情况。
- 其他配置选项： OpenAPI Generator提供了大量的配置选项，可以控制生成的代码的各个方面，如日期时间格式、集合类型、包名等。建议查阅官方文档以获取更全面的信息：OpenAPI Generator Configuration。
- 重新生成： 每次修改配置后，都需要重新运行Gradle的OpenAPI生成任务，以使更改生效。
总结
通过灵活运用OpenAPI Generator的identifierNamingConvention配置选项，开发者可以有效地控制Java代码生成过程中模型字段的命名规范。将此选项设置为original，能够确保生成的Java字段与OpenAPI规范中定义的名称保持一致，从而满足特定的项目需求和编码风格。这对于需要高度控制代码生成细节的专业项目尤为重要。
