OpenAPI Generator Maven插件处理含相对路径$ref的YAML无法生成Java代码如何解决

API 探路者

2026-9-28

问题根因

你遇到的StringIndexOutOfBoundsException异常是5.1.0版本openapi-generator-maven-plugin内置的swagger-parser组件存在Windows绝对路径解析缺陷：当inputSpec使用盘符开头的本地绝对路径时，解析同目录下的相对路径$ref会触发字符串下标计算错误。

解决方法

按优先级从高到低选择即可：

方案1：升级插件版本
直接升级openapi-generator-maven-plugin到最新稳定版（7.x及以上），官方已修复该路径解析bug，无需修改其他配置即可正常解析相对路径$ref。
方案2：修改inputSpec为相对路径
若因项目限制不能升级插件版本，将inputSpec的绝对路径改为相对于maven执行根目录的相对路径，示例：
```
<inputSpec>${project.basedir}/src/main/resources/openapi/provMnS.yaml</inputSpec>
```
方案3：显式指定引用根目录
必须使用绝对路径的场景下，在configuration节点下添加basePath配置指定YAML文件的根目录：
```
<basePath>C:/Users/xxxxx/Documents/Docs/Project/xxxxyy/workspace1/MnS-Rel-16/MnS-Rel-16/OpenAPI/</basePath>
```

完整配置示例

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>7.6.0</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi/provMnS.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <modelPackage>com.xxx.xxx.dto.etsi.moi</modelPackage>
                <resolveFully>true</resolveFully>
                <configOptions>
                    <interfaceOnly>true</interfaceOnly>
                    <skipDefaultInterface>true</skipDefaultInterface>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

验证注意事项