如何为Spring Boot + Jersey应用添加Swagger相关静态文件？

针对你用Spring Boot 2.0.1 + Jersey 2.0.1 + Swagger 1.5.18搭建项目时遇到的Swagger静态内容（HTML/JS）配置问题，我整理了一套完整的解决方案，一步步来就能搞定：

1. 先补全依赖 #

你现有的swagger-jersey2-jaxrs只负责生成API文档的JSON数据，Swagger UI的静态文件需要单独引入swagger-ui依赖，在pom.xml里加上：

<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>1.5.18</version>
</dependency>

2. 完善Swagger配置类 #

你的SwaggerConfig需要把BeanConfig配置完整，还要注册Swagger的Jersey资源，这样Swagger才能处理API文档的请求：

@Configuration
public class SwaggerConfig {

    @Bean
    public BeanConfig swaggerConfiguration() {
        final BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0"); // 替换成你的API版本
        beanConfig.setSchemes(new String[]{"http"}); // 生产环境可以改成https
        beanConfig.setHost("localhost:8080"); // 替换成你的服务地址和端口
        beanConfig.setBasePath("/api"); // 替换成你的Jersey API基础路径
        beanConfig.setResourcePackage("com.your.api.package"); // 替换成你放API接口的包路径
        beanConfig.setTitle("你的REST API文档");
        beanConfig.setDescription("Spring Boot + Jersey项目的API说明");
        beanConfig.setScan(true); // 开启包扫描，自动识别带Swagger注解的接口
        return beanConfig;
    }

    // 注册Swagger的Jersey核心资源
    @Bean
    public ResourceConfig jerseyConfig() {
        ResourceConfig config = new ResourceConfig();
        // 注册你的API接口所在包
        config.packages("com.your.api.package");
        // 必须注册这两个类，Swagger才能生成和返回API文档
        config.register(ApiListingResource.class);
        config.register(SwaggerSerializers.class);
        return config;
    }
}

3. 配置静态资源映射 #

Swagger UI的静态文件（index.html、JS/CSS）都在swagger-ui依赖的META-INF/resources/webjars目录下，Spring Boot默认会处理/webjars/**路径，但如果你的Jersey配置了@ApplicationPath("/")（拦截所有请求），就得手动加个配置让Spring Boot接管Swagger静态资源：

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 把/swagger-ui/**路径映射到swagger-ui的静态资源目录
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/1.5.18/");
    }
}

如果你的Jersey是用@ApplicationPath("/api")（只拦截API路径），这一步可以跳过，Spring Boot会自动处理静态资源。

4. 验证访问 #

启动项目后，直接访问http://localhost:8080/swagger-ui/index.html就能看到Swagger UI界面了。对应的API文档JSON地址是http://localhost:8080/api/swagger.json（如果你的basePath是/api），Swagger UI会自动加载这个文档。

常见坑排查 #

• 要是访问Swagger UI出现404，先检查swagger-ui依赖有没有正确引入，静态资源映射的版本号（1.5.18）是不是和你用的依赖版本一致
• 确保BeanConfig里的resourcePackage是你放API接口的包，而且接口类上要加@Api注解，方法加@ApiOperation等Swagger注解，不然扫描不到
• 要是Jersey拦截了静态资源，检查@ApplicationPath的配置，或者手动加上面的WebMvcConfig映射

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