在使用 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 规范中定义的原始大小写。
精确控制字段命名：使用 identifierNamingConvention
OpenAPI Generator 提供了丰富的配置选项来定制生成过程，其中 identifierNamingConvention 就是用于控制标识符命名规则的关键选项。通过修改此选项，我们可以指定生成的字段、方法等标识符应遵循的命名约定。
要解决字段大小写被修改的问题，只需将 identifierNamingConvention 配置为 "original"。这将指示生成器完全保留 OpenAPI 规范中定义的原始字段名称，不做任何大小写转换。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
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 规范中的定义完全一致。这对于维护命名一致性、简化与现有系统集成以及遵循特定编码标准至关重要。在应用此配置时，请务必结合项目实际需求和目标语言的通用实践进行权衡。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
