是否可通过$ref引用依赖jar包内的外部OpenAPI规范文件？

可行性结论 #

可以实现该需求，触发Unable to load RELATIVE ref报错的核心原因是OpenAPI Generator默认的文件解析器仅扫描当前项目的本地文件路径，不会自动加载、解析依赖JAR包内部的资源文件。

可用实现方案 #

方案1：基于类路径协议直接引用（无需解压文件） #

1. 放弃相对路径写法，将$ref的取值改为类路径协议格式，示例如下：

$ref: classpath:/shared-specs/user-common.yaml

2. 调整构建插件配置，将包含共享API规范的依赖添加到OpenAPI Generator插件的运行时类路径中，同时开启全量解析配置。以Maven配置为例：

<plugin>
    <groupId>org.openapitools</groupId>
    <artifactId>openapi-generator-maven-plugin</artifactId>
    <version>${openapi-generator.version}</version>
    <dependencies>
        <!-- 引入包含共享规范的依赖 -->
        <dependency>
            <groupId>com.your.company</groupId>
            <artifactId>shared-api-spec</artifactId>
            <version>${shared-spec.version}</version>
        </dependency>
        <!-- 补充类路径解析支持 -->
        <dependency>
            <groupId>io.swagger.parser.v3</groupId>
            <artifactId>swagger-parser</artifactId>
            <version>${swagger-parser.version}</version>
        </dependency>
    </dependencies>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <inputSpec>${project.basedir}/src/main/resources/openapi/main.yaml</inputSpec>
                <generatorName>spring</generatorName>
                <configOptions>
                    <resolveFully>true</resolveFully>
                </configOptions>
            </configuration>
        </execution>
    </executions>
</plugin>

3. 若两份处于不同依赖JAR的规范需要互指，双方的$ref均统一使用classpath:前缀的全类路径写法即可，只要两个依赖都添加到插件的运行时类路径中就能正常解析。

方案2：提前解压JAR内规范到本地构建目录 #

如果不想调整插件类路径，可以使用构建插件提前把依赖JAR内的规范文件解压到本地项目的构建目录，再用相对路径引用：

1. 以Maven为例，配置maven-dependency-plugin在生成代码前执行解压操作：

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-dependency-plugin</artifactId>
    <executions>
        <execution>
            <id>unpack-shared-specs</id>
            <phase>generate-sources</phase>
            <goals>
                <goal>unpack</goal>
            </goals>
            <configuration>
                <artifactItems>
                    <artifactItem>
                        <groupId>com.your.company</groupId>
                        <artifactId>shared-api-spec</artifactId>
                        <version>${shared-spec.version}</version>
                        <type>jar</type>
                        <outputDirectory>${project.build.directory}/openapi/shared</outputDirectory>
                        <includes>**/*.yaml</includes>
                    </artifactItem>
                </artifactItems>
            </configuration>
        </execution>
    </executions>
</plugin>

2. 项目内的$ref直接写相对于构建目录的相对路径即可，OpenAPI Generator可以直接识别本地文件路径的引用。

替代依赖推荐 #

如果OpenAPI Generator的配置成本较高，可以改用springdoc-openapi-maven-plugin配合swagger-parser-v3，该组合默认支持类路径资源扫描，只要把包含共享规范的依赖添加到项目的常规依赖列表中，就可以直接读取JAR包内部的OpenAPI规范文件，无需额外配置插件类路径。

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