如何通过Spring版OpenAPI Generator生成带JPA关联注解的实体类？

我用Spring版OpenAPI Generator生成Spring Boot实体类时，没法给关联其他实体的字段加上@OneToOne、@OneToMany这类JPA关联注解。

期望生成的Customer实体类 #

@jakarta.persistence.Entity @jakarta.persistence.Table(name = "customers")
public class Customer {

  @JsonProperty("user")
  @jakarta.persistence.OneToOne
  private User user;
}

我的Maven配置 #

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
...
    <build>
        <plugins>
            <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <version>6.2.1</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>${project.basedir}/../../openapi/openapi.yml</inputSpec>
                            <generatorName>spring</generatorName>
                            <output>${project.basedir}</output>
                            <configOptions>
                                <sourceFolder>src/main/java</sourceFolder>
                                <delegatePattern>true</delegatePattern>
                                <useSpringBoot3>true</useSpringBoot3>
                                <hideGenerationTimestamp>true</hideGenerationTimestamp>
                            </configOptions>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
...
</project>

已尝试的两种失败方法 #

方法1：直接用$ref指定字段类型 #

openapi.yml配置：

openapi: 3.0.2
components:
  schemas:
    User:
      description: ""
      type: object
      properties:
        id:
          description: ""
          type: UUID
          x-field-extra-annotation: '@jakarta.persistence.Id'
      x-class-extra-annotation: '@jakarta.persistence.Entity @jakarta.persistence.Table(name
        = "users")'
    Customer:
      description: ""
      type: object
      properties:
        user:
          $ref: '#/components/schemas/User'
          description: ""
          x-field-extra-annotation: '@jakarta.persistence.OneToOne'
        id:
          description: ""
          type: UUID
          x-field-extra-annotation: '@jakarta.persistence.Id'
      x-class-extra-annotation: '@jakarta.persistence.Entity @jakarta.persistence.Table(name
        = "customers")'

问题：生成的Customer实体中user字段类型正确，但@OneToOne注解没生成——因为OpenAPI的$ref会忽略同级的所有元素。

方法2：用anyOf作为临时方案 #

openapi.yml配置：

openapi: 3.0.2
components:
  schemas:
    User:
      description: ""
      type: object
      properties:
        id:
          description: ""
          type: UUID
          x-field-extra-annotation: '@jakarta.persistence.Id'
      x-class-extra-annotation: '@jakarta.persistence.Entity @jakarta.persistence.Table(name
        = "users")'
    Customer:
      description: ""
      type: object
      properties:
        user:
          anyOf:
            - $ref: '#/components/schemas/User'
          description: ""
          x-field-extra-annotation: '@jakarta.persistence.OneToOne'
        id:
          description: ""
          type: UUID
          x-field-extra-annotation: '@jakarta.persistence.Id'
      x-class-extra-annotation: '@jakarta.persistence.Entity @jakarta.persistence.Table(name
        = "customers")'

问题：生成了多余的CustomerUser类，而且Customer的user字段类型变成了CustomerUser而非User，不符合需求。

解决方案 #

有三种可行的方式解决这个问题：

1. 使用x-jpa-relation扩展注解（推荐） #

从OpenAPI Generator 7.x版本开始，官方支持x-jpa-relation扩展字段，可直接在$ref同级配置关联信息，同时保留x-field-extra-annotation生成注解：

修改后的openapi.yml中Customer的user字段配置：

user:
  $ref: '#/components/schemas/User'
  x-jpa-relation:
    type: "one-to-one"
    target-entity: "com.your.package.User" # 替换为User类的实际全限定名
  x-field-extra-annotation: '@jakarta.persistence.OneToOne'

如果当前使用的6.2.1版本不支持该扩展，建议升级到7.x及以上版本。

2. 自定义Mustache模板 #

如果不想升级版本，可以修改Spring生成器的实体类模板：

• 找到对应版本的model.mustache模板（可从OpenAPI Generator仓库获取）
• 在字段注解生成逻辑中，添加对x-field-extra-annotation的读取逻辑，即使字段是$ref类型也保留该注解
• 在Maven插件配置中指定自定义模板路径：

<configuration>
  <!-- 原有配置 -->
  <templateDirectory>${project.basedir}/src/main/resources/openapi-templates</templateDirectory>
</configuration>

这种方式适合需要高度定制生成代码的场景，需熟悉Mustache模板语法。

3. 用allOf替代anyOf（临时兼容方案） #

如果暂时无法升级或修改模板，可使用allOf包装$ref——当allOf中只有一个$ref时，Generator会直接引用目标类，不会生成多余的中间类，同时能保留同级的扩展注解：

user:
  allOf:
    - $ref: '#/components/schemas/User'
  x-field-extra-annotation: '@jakarta.persistence.OneToOne'

内容的提问来源于stack exchange，提问作者Benjamin