Swagger 1.5.18配置scan.all.resources扫描JAXRS无注解类问题

我之前在使用Swagger 1.5.x版本时也碰到过一模一样的问题——带Swagger注解的类能正常出现在swagger.json里，但纯JAXRS（仅带@Path注解）的资源类死活扫不到。结合踩过的坑，给你几个实测有效的解决方案：

1. 正确配置BeanConfig的扫描属性 #

如果是用继承Application的类配置Swagger，一定要在BeanConfig中开启扫描所有资源的开关，这是最关键的一步：

public class MyJaxrsApplication extends Application {
    public MyJaxrsApplication() {
        BeanConfig beanConfig = new BeanConfig();
        beanConfig.setVersion("1.0.0");
        beanConfig.setSchemes(new String[]{"http"});
        beanConfig.setHost("localhost:8080");
        beanConfig.setBasePath("/your-api-base-path");
        // 核心配置：开启扫描所有JAXRS资源，包括无Swagger注解的类
        beanConfig.setScanAllResources(true);
        // 指定要扫描的包路径，确保你的@Path类在这个包下
        beanConfig.setResourcePackage("com.your.project.resources");
        // 启动扫描
        beanConfig.setScan(true);
    }

    @Override
    public Set<Class<?>> getClasses() {
        // 这里可以返回你的资源类集合，或者留空让Swagger自动扫描
        return new HashSet<>();
    }
}

注意：setScanAllResources(true)是Swagger 1.5.x专门用来控制是否扫描所有JAXRS资源的属性，默认是false，只会扫描带Swagger注解（比如@Api）的类，所以一定要显式设置为true。

2. 修正DefaultJaxrsConfig的初始化参数 #

如果你用继承DefaultJaxrsConfig的Servlet方式配置，要注意参数名的正确性——你之前用的scan.all.resources是错的，正确的参数名应该是swagger.scan.all.resources：

@WebServlet(
    name = "SwaggerConfigServlet",
    urlPatterns = "/swagger/*",
    loadOnStartup = 1, // 确保Servlet优先加载
    initParams = {
        @WebInitParam(name = "swagger.api.basepath", value = "/your-api-base-path"),
        @WebInitParam(name = "swagger.resource.package", value = "com.your.project.resources"),
        // 正确的参数名
        @WebInitParam(name = "swagger.scan.all.resources", value = "true")
    }
)
public class CustomSwaggerConfigServlet extends DefaultJaxrsConfig {
    public CustomSwaggerConfigServlet() {
        super();
    }
}

另外，设置loadOnStartup=1能保证Swagger配置Servlet在你的JAXRS应用之前加载，避免扫描时机不对导致的问题。

3. 排查类路径与扫描范围问题 #

Swagger是通过反射扫描类路径下的类，所以要确保：

• 你的@Path资源类确实在resourcePackage指定的包路径下
• 如果是多模块项目，Swagger所在的模块能访问到资源类的字节码（比如Maven依赖是否正确）
• 不要把资源类放在未被类加载器扫描到的路径下（比如某些自定义的类加载器场景）

4. 手动注册资源类（兜底方案） #

如果上面的配置都不生效，可以手动把纯@Path类注册到Swagger中：

// 在你的Application初始化或Servlet init方法中
Swagger swagger = SwaggerContextService.getSwagger();
JaxrsApiReader apiReader = new JaxrsApiReader();

// 手动读取并添加你的资源类
ApiDeclaration apiDecl = apiReader.read(YourPathOnlyResource.class, swagger);
swagger.addResourceListing(ResourceListing.builder()
        .apiDeclaration(apiDecl)
        .build());

这种方式虽然繁琐，但能确保资源类被Swagger识别，适合一些特殊场景。

内容的提问来源于stack exchange，提问作者Brian S Paskin