拆分OpenAPI文件后openapi-generator-maven-plugin未生成Name对象问题

问题原因 #

1. 相对文件引用解析异常：Code.json中直接使用./Name.json的文件路径引用，而OpenAPI Generator处理拆分规范时，需要通过组件内引用（#/components/schemas/Name）识别已注册的Schema，而非直接文件路径。
2. 跳过规范验证掩盖错误：配置中开启<skipValidateSpec>true</skipValidateSpec>，导致插件未检测到引用路径不合法的问题。

解决方案 #

1. 修正Code.json中的引用路径 #

将Code.json里的数组元素引用改为组件Schema引用：

{
    "type": "object",
    "properties": {
        "value": {
            "type": "string"
        },
        "names": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Name"
            }
        }
    }
}

2. 调整插件配置以支持完整引用解析 #

关闭跳过验证，并添加配置确保插件完全解析所有嵌套引用：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>6.6.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <skipValidateSpec>false</skipValidateSpec>
                <inputSpec>${openapi.input.file}</inputSpec>
                <generatorName>spring</generatorName>
                <apiPackage>com.pack.example.controller</apiPackage>
                <modelPackage>com.pack.example.dto</modelPackage>
                <supportingFilesToGenerate>
                    ApiUtil.java
                </supportingFilesToGenerate>
                <resolveFully>true</resolveFully>
                <configOptions>
                    <useSpringBoot3>true</useSpringBoot3>
                    <useTags>true</useTags>
                    <delegatePattern>true</delegatePattern>
                    <serializableModel>true</serializableModel>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

3. 验证文件结构合法性 #

确认所有拆分文件的引用逻辑正确：

• schemas/_index.json已正确注册Name和Code Schema
• parameters、responses等组件的引用路径无错误

验证结果 #

执行mvn clean generate后，插件会正确生成Name类，且Code类中的names数组元素类型会变为Name而非Object。

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