从application properties加载文件时API定义加载失败求助

我通过RestDocs生成并转换得到了OpenAPI文件，已将其放入resources目录，且配置文件已指向该文件，但Swagger加载失败，不清楚遗漏了哪些配置。相关依赖与插件配置如下：

<dependency>
    <groupId>org.springframework.restdocs</groupId>
    <artifactId>spring-restdocs-mockmvc</artifactId>
    <version>${spring-restdocs-mockmvc.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>${springdoc-openapi-ui.version}</version>
</dependency>
<dependency>
    <groupId>capital.scalable</groupId>
    <artifactId>spring-auto-restdocs-core</artifactId>
    <version>${spring-auto-restdocs-core.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>com.epages</groupId>
    <artifactId>restdocs-api-spec</artifactId>
    <version>${restdocs-api-spec.version}</version>
    <scope>test</scope>
</dependency>
<dependency>
    <groupId>com.epages</groupId>
    <artifactId>restdocs-api-spec-mockmvc</artifactId>
    <version>${restdocs-api-spec.version}</version>
    <scope>test</scope>
</dependency>

<plugin>
    <groupId>io.github.berkleytechnologyservices</groupId>
    <artifactId>restdocs-spec-maven-plugin</artifactId>
    <version>${restdocs-spec.version}</version>
    <executions>
        <execution>
            <goals>
                <goal>generate</goal>
            </goals>
            <configuration>
                <!--suppress MavenModelInspection -->
                <skip>${skipTests}</skip>
                <host>localhost:8081</host>
                <specification>OPENAPI_V3</specification>
                
                <outputDirectory>${project.build.directory}/classes/static/docs</outputDirectory>
            </configuration>
        </execution>
    </executions>
</plugin>

排查步骤 #

• 校验OpenAPI文件规范
  使用OpenAPI校验工具检查生成的yaml/json文件是否符合V3规范，语法错误是加载失败的常见诱因。

• 确认配置文件路径准确性
  检查springdoc配置中指定的OpenAPI文件路径是否正确，示例配置：

  springdoc.swagger-ui.url=/docs/openapi.yaml
  

  路径需与文件实际位置匹配：若文件放在resources/static/docs/，访问路径为/docs/openapi.yaml；若在resources根目录，则为/openapi.yaml。

• 验证资源目录访问权限
  确保存放OpenAPI文件的目录被Spring Boot识别为静态资源目录。默认resources/static/可直接访问，自定义目录需配置spring.web.resources.static-locations。

• 统一插件输出与资源目录
  插件输出目录为${project.build.directory}/classes/static/docs，该目录会被打包到运行时的static/docs。若手动将文件放入resources目录，需确保两者路径一致，或修改插件输出路径为src/main/resources/static/docs，避免路径冲突。

• 检查依赖版本兼容性
  确认springdoc-openapi-ui版本与Spring Boot版本匹配：Spring Boot 3.x对应springdoc v2.x，Spring Boot 2.x对应springdoc v1.x。同时保证RestDocs相关依赖与Spring Boot版本兼容。

• 查看应用日志定位错误
  启动应用时搜索springdoc或swagger相关日志，文件找不到、解析错误等信息可直接定位问题根源。

• 确认Swagger UI访问路径
  默认访问路径为/swagger-ui.html，若配置了自定义路径，需确保访问地址正确且映射到springdoc的UI控制器。

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