使用Atlassian库校验Swagger时无法从自定义目录读取规范怎么办

问题根因 #

Maven、Gradle等Java项目构建工具默认仅会将src/main/resources目录下的文件自动打包到运行时类路径。你之前将Swagger规范放在src/main/api可正常运行，说明该目录已经被提前配置为项目的资源扫描目录；新增的src/main/swagger、src/main/api/swaggers未被纳入资源扫描范围，导致构建后的类路径中不存在对应文件，就会抛出java.lang.RuntimeException: Could not find /api/swaggers/swagger.yml on the classpath异常。

解决方案 #

方式1：修改构建配置，将目标目录纳入资源扫描范围 #

Maven 配置

在pom.xml的build/resources节点增加对应目录的配置即可：

<build>
    <resources>
        <!-- 保留默认的resources目录配置，避免原有资源加载异常 -->
        <resource>
            <directory>src/main/resources</directory>
        </resource>
        <!-- 新增swagger文件存放目录的配置 -->
        <resource>
            <directory>src/main/swagger</directory>
        </resource>
        <resource>
            <directory>src/main/api/swaggers</directory>
        </resource>
    </resources>
</build>

Gradle 配置

在build.gradle的sourceSets中增加资源目录配置即可：

sourceSets {
    main {
        resources {
            srcDirs += ["src/main/swagger", "src/main/api/swaggers"]
        }
    }
}

方式2：调整文件存放位置与路径参数 #

如果不想修改构建配置，可直接将Swagger规范文件移动到src/main/resources下的对应子目录，创建校验器时传入相对类路径的路径即可。比如文件放在src/main/resources/swaggers/swagger.yml，代码修改为：

private static final OpenApiValidationFilter SWAGGER_FILTER_ = new OpenApiValidationFilter(
    OpenApiInteractionValidator.createFor("/swaggers/swagger.yml")
        .withBasePathOverride("ApiBasePath")
        .build());

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