使用springdoc-openapi-starter-webmvc-ui加载自定义openapi.yaml失败

你当前的核心问题是配置项使用错误：springdoc.api-docs.path的作用是修改自动生成的API文档的访问路径（默认值为/v3/api-docs），并非用来加载自定义的OpenAPI规范文件，这才导致Swagger UI提示Failed to load remote configuration。

以下是两种可行的解决方案：

方案1：让Swagger UI直接加载静态资源中的YAML文件 #

1. 将你的swagger-config.yaml文件移动到src/main/resources/static目录下（Spring Boot会自动将该目录下的文件暴露为可访问的静态资源）
2. 修改application.properties中的配置：

   # 配置Swagger UI加载指定的YAML文件
   springdoc.swagger-ui.url=/swagger-config.yaml
   

3. 重启服务后访问Swagger UI，即可正常加载自定义的OpenAPI规范。

方案2：让springdoc加载自定义YAML作为API文档源（替换自动生成内容） #

如果希望让/v3/api-docs接口返回你自定义的YAML内容（替代自动生成的接口文档），可以这样配置：

1. 将swagger-config.yaml放在src/main/resources目录下
2. 修改application.properties：

   # 指定加载自定义OpenAPI规范文件
   springdoc.openapi.location=classpath:/swagger-config.yaml
   

3. 重启服务后，访问/v3/api-docs会返回你的自定义YAML内容，Swagger UI默认会加载该路径，无需额外配置即可正常显示。

额外检查点 #

• 确认swagger-config.yaml文件路径配置正确，文件确实存在于指定的classpath目录中
• 若需要同时保留自动生成的接口文档和自定义规范，可以通过分组配置实现：

  springdoc.group-configs[0].group=default
  springdoc.group-configs[1].group=custom
  springdoc.group-configs[1].openapi-location=classpath:/swagger-config.yaml
  

  此时Swagger UI会显示两个分组选项，可切换查看不同的文档。

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