OpenAPI Generator Java 代码生成：精确控制字段命名大小写

在使用 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 规范中定义的原始字段名称，不做任何大小写转换。

BlessAI

Bless AI 提供五个独特的功能：每日问候、庆祝问候、祝福、祷告和名言的文本生成和图片生成。

89

查看详情

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;

注意事项：

1. Jackson @JsonProperty 行为： 即使 Java 字段名通过 identifierNamingConvention: "original" 保持了原始大小写，@com.fasterxml.jackson.annotation.JsonProperty 注解中的值（如 JSON_PROPERTY_A_I_O_B_CATEGORY）可能仍然会遵循其内部的命名策略，将其转换为某种标准格式（如大写蛇形）。但这通常不影响 Java 字段本身的命名和 JSON 序列化/反序列化。
2. 其他命名约定： identifierNamingConvention 除了 "original" 外，还支持其他值，例如 "snake_case"（蛇形命名）、"camelCase"（小驼峰命名，通常是默认值）、"PascalCase"（大驼峰命名）等。选择哪种约定取决于您的项目需求和团队规范。
3. GeneratorName 的选择： 示例中使用了 java，但根据您的具体需求（如 Spring Boot 项目），您可能需要选择 spring、jaxrs-spec 等其他生成器。不同的生成器可能对某些配置项有特定的行为或默认值。
4. 官方文档查阅： 强烈建议查阅 OpenAPI Generator 的官方配置文档（https://openapi-generator.tech/docs/configuration），以获取最全面和最新的配置选项信息，特别是针对您使用的特定生成器。

总结

通过在 OpenAPI Generator 配置中设置 identifierNamingConvention: "original"，您可以有效地控制 Java 代码生成过程中字段的命名大小写，确保其与 OpenAPI 规范中的定义完全一致。这对于维护命名一致性、简化与现有系统集成以及遵循特定编码标准至关重要。在应用此配置时，请务必结合项目实际需求和目标语言的通用实践进行权衡。

以上就是OpenAPI Generator Java 代码生成：精确控制字段命名大小写的详细内容，更多请关注php中文网其它相关文章！