如何通过YAML/JSON配置托管Swagger文档？加载失败问题排查

我尝试在Swagger配置中添加自定义swagger.yaml文件以在Swagger UI中展示，使用如下Java配置代码：

@Configuration
@EnableSwagger2
public class SwaggerConfig2 extends WebMvcConfigurerAdapter {

    @Primary
    @Bean
    public SwaggerResourcesProvider swaggerResourcesProvider() {
        return () -> {
            SwaggerResource wsResource = new SwaggerResource();
            wsResource.setName("Documentation");
            wsResource.setSwaggerVersion("2.0");
            wsResource.setLocation("/swagger.yaml");

            List<SwaggerResource> resources = List.of(wsResource);
            return resources;
        };
    }

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
        registry.addResourceHandler("/swagger.yaml").addResourceLocations("classpath:/swagger.yaml");
    }

}

但访问http://localhost:8078/swagger-ui.html#/时，出现“Failed to load API definition.”和“Fetch errorundefined http://localhost:8078/swagger.yaml”错误，可按以下步骤排查解决：

1. 修正资源映射配置 #

addResourceLocations参数指定的是资源所在目录，而非具体文件路径。原代码中直接指向classpath:/swagger.yaml会导致路径解析错误，修改为：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    // 修正为目录路径
    registry.addResourceHandler("/swagger.yaml").addResourceLocations("classpath:/");
}

2. 确认文件位置 #

确保swagger.yaml文件放置在src/main/resources根目录下，这样打包后文件会被正确放入classpath根路径，能被资源映射匹配到。

3. 检查上下文路径与请求拦截 #

• 如果应用配置了上下文路径（如server.servlet.context-path=/api），需要同步修改SwaggerResource的路径：

  wsResource.setLocation("/api/swagger.yaml");
  

• 若项目使用Spring Security或自定义拦截器，需允许/swagger.yaml及Swagger相关路径的匿名访问，示例Security配置：

  @Override
  protected void configure(HttpSecurity http) throws Exception {
      http.authorizeRequests()
          .antMatchers("/swagger-ui.html", "/swagger.yaml", "/webjars/**", "/v2/api-docs")
          .permitAll()
          .anyRequest().authenticated();
  }
  

4. 验证Swagger.yaml语法合法性 #

yaml文件语法错误会导致加载失败，可通过本地或在线的Swagger Editor验证文件格式是否符合OpenAPI 2.0规范。

5. 前置测试 #

重启服务后，先直接访问http://localhost:8078/swagger.yaml，确认能正常返回文件内容，再打开Swagger UI查看API定义是否加载成功。

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