Spring Boot项目Maven openapi插件多OpenAPI YAML引用报错如何解决

核心问题原因 #

报错由两个核心问题导致：

1. 主openapi.yaml中$ref指向的JSON路径不符合OpenAPI规范，未正确定位到子文件中的对应节点
2. 5.1.1版本的openapi-generator-maven-plugin内置的swagger解析器存在相对路径解析bug

具体修复步骤 #

1. 修正所有$ref引用路径 #

OpenAPI的相对引用需要定位到目标文件中的完整JSON路径，路径中的/需要转义为~1：

• 引用子文件paths下的接口：例如要引用user.yaml中paths节点下的/user接口，正确写法为$ref: 'user.yaml#/paths/~1user'
• 引用子文件components下的 schema：例如要引用user.yaml中的User结构体，正确写法为$ref: 'user.yaml#/components/schemas/User'
• 修正笔误：你当前配置中$ref: 'pet.api.yaml#/version'为错误文件名，需修正为实际存在的文件名
• 确认所有引用的子文件（如structureGroupLocation.yaml）都存放在src/main/resources目录下，文件名大小写与引用路径完全一致

修正后的主文件paths片段示例：

paths:
  /user:
    $ref: 'user.yaml#/paths/~1user'
  /user/createWithArray:
    $ref: 'user.yaml#/paths/~1user~1createWithArray'
  /user/createWithList:
    $ref: 'user.yaml#/paths/~1user~1createWithList'
  /user/login:
    $ref: 'user.yaml#/paths/~1user~1login'
  /user/logout:
    $ref: 'user.yaml#/paths/~1user~1logout'
  /version:
    $ref: 'version.yaml#/paths/~1version'
components:
  schemas:
    User:
      $ref: 'user.yaml#/components/schemas/User'
    Version:  
      $ref: 'version.yaml#/components/schemas/Version'

2. 优化子文件结构（可选但推荐） #

子文件不需要保留完整的openapi、info、servers等冗余配置，仅保留需要被引用的paths、components节点即可，降低解析负担。

3. 修复Maven插件配置 #

在插件配置中开启外部引用解析，同时升级内置的swagger解析器版本修复相对路径bug：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>5.1.1</version>
    <!-- 升级解析器依赖修复相对路径bug -->
    <dependencies>
        <dependency>
            <groupId>io.swagger.parser.v3</groupId>
            <artifactId>swagger-parser</artifactId>
            <version>2.1.16</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <phase>generate-sources</phase>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <!-- 开启外部引用解析 -->
                <resolveExternalRefs>true</resolveExternalRefs>
                <supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>
                <configOptions>
                    <delegatePattern>true</delegatePattern>
                    <interfaceOnly>true</interfaceOnly>
                </configOptions>
                <modelPackage>${project.groupId}.openapi.DTO</modelPackage>
                <apiPackage>${project.groupId}.openapi.api</apiPackage>
            </configuration>
        </execution>
    </executions>
</plugin>

验证 #

修改完成后执行mvn clean generate-sources即可正常生成代码。

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