OpenAPI Generator Maven插件（Spring）未按预期生成分离Schema的x-extra-annotation

问题描述 #

我希望在共享Schema上定义注解以避免重复配置。当直接在Schema的属性上定义x-extra-annotation时，生成器会按预期将注解添加到getter方法上；但将该属性提取为独立Schema并在其中定义注解后，生成的模型中并未包含该额外注解。尝试了字段注解的厂商扩展，在独立Schema上同样无法生效。

直接定义属性的Schema（生效） #

components:
  schemas:
    Person:
      type: object
      required:
        - firstname
        - surname
      properties:
        firstname:
          type: string
        surname:
          type: string
          x-extra-annotation: "@SurnameAnnotation"

生成的Person类中surname的getter包含@SurnameAnnotation注解。

提取为独立Schema的配置（不生效） #

components:
  schemas:
    Person:
      type: object
      required:
        - firstname
        - surname
      properties:
        firstname:
          type: string
        surname:
          type: surname
    surname:
      type: string
      x-extra-annotation: "@SurnameAnnotation"

生成的Person类中surname的getter无@SurnameAnnotation注解。

使用的插件配置 #

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.4.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>
                    ${project.basedir}/src/main/resources/openapi/helloworld.yml
                </inputSpec>
                <templateDirectory>
                    ${project.basedir}/src/main/resources/openapi/templates/
                </templateDirectory>
                <generatorName>spring</generatorName>
                <apiPackage>nl.myorg.poc</apiPackage>
                <modelPackage>nl.myorg.poc.models</modelPackage>
                <supportingFilesToGenerate></supportingFilesToGenerate>
                <configOptions>
                    <skipDefaultInterface>true</skipDefaultInterface>
                    <interfaceOnly>true</interfaceOnly>
                    <useSpringBoot3>true</useSpringBoot3>
                    <useTags>true</useTags>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

正确的注解添加方式 #

方案1：修改模板逻辑，让生成器读取引用Schema的扩展 #

OpenAPI Generator默认不会自动继承引用Schema的扩展注解，需要调整自定义模板的逻辑，让生成器处理$ref属性时读取引用Schema的x-extra-annotation：

1. 找到你配置的templateDirectory下的model.mustache模板文件
2. 在处理getter注解的代码块中，添加读取引用Schema扩展的逻辑：

{{#vars}}
    {{#isGet}}
        {{#vendorExtensions.x-extra-annotation}}{{{.}}}{{/vendorExtensions.x-extra-annotation}}
        {{#refSchema}}
            {{#vendorExtensions.x-extra-annotation}}{{{.}}}{{/vendorExtensions.x-extra-annotation}}
        {{/refSchema}}
        public {{datatype}} {{getter}}() {
            return {{name}};
        }
    {{/isGet}}
{{/vars}}

调整后，生成器会优先读取当前属性的扩展，若没有则自动读取引用Schema的x-extra-annotation，实现注解复用。

方案2：引用共享Schema时显式指定注解（简单直接） #

如果不想修改模板，可以在引用共享Schema的属性节点上显式添加x-extra-annotation，虽然会重复注解配置，但能保证生成器正常识别：

components:
  schemas:
    Person:
      type: object
      required:
        - firstname
        - surname
      properties:
        firstname:
          type: string
        surname:
          $ref: '#/components/schemas/Surname'
          x-extra-annotation: "@SurnameAnnotation"
    Surname:
      type: string

方案3：映射到自定义带注解的Java类 #

如果共享Schema对应独立的Java类型，可以手动创建带注解的类，再通过插件配置映射：

1. 手动创建带注解的Java类：

package nl.myorg.poc.models;

@SurnameAnnotation
public class Surname {
    private String value;

    // getter、setter方法
}

2. 修改OpenAPI配置，用$ref引用共享Schema：

components:
  schemas:
    Person:
      type: object
      required:
        - firstname
        - surname
      properties:
        firstname:
          type: string
        surname:
          $ref: '#/components/schemas/Surname'
    Surname:
      type: string

3. 在插件的configOptions中添加映射配置：

<importMappings>
    <importMapping>Surname=nl.myorg.poc.models.Surname</importMapping>
</importMappings>

这样生成的Person类会直接引用自定义的Surname类，自带目标注解。

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