如何在非简易Wildfly Swarm项目中正确使用Swagger？

我之前碰到过类似的场景，Wildfly Swarm集成Swagger时，默认扫描范围通常只覆盖初始的REST包，新增第二个包后没被纳入扫描范围，就会导致swagger.json无法正常生成。给你几个实用的解决办法：

1. 通过注解指定Swagger扫描包范围 #

在应用的启动类或者专门的Swagger配置类上，用@Scan注解明确列出所有需要扫描的包：

import io.swagger.annotations.SwaggerDefinition;
import io.swagger.annotations.Scan;

@SwaggerDefinition
@Scan(basePackages = {"ch.schlau.pesche.swagger42.rest", "你的第二个包完整路径"})
public class SwaggerConfig {
    // 无需额外代码，仅作为注解载体
}

这样Swagger就会同时扫描两个包下的REST端点和Swagger注解。

2. 通过配置文件扩展扫描范围 #

如果使用Wildfly Swarm的swagger fraction，也可以在project-defaults.yml或swarm.yml里配置扫描包：

swarm:
  swagger:
    scan:
      packages:
        - ch.schlau.pesche.swagger42.rest
        - 你的第二个包完整路径

这种方式不用修改代码，配置更灵活。

3. 检查新包下REST类的Swagger注解 #

有时候不是扫描问题，而是新包下的REST类没添加Swagger识别所需的注解。记得给新类和方法加上对应的注解，比如：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import javax.ws.rs.GET;
import javax.ws.rs.Path;

@Path("/new-api")
@Api(tags = "新增接口组")
public class NewRestEndpoint {

    @GET
    @ApiOperation(value = "获取测试数据", notes = "返回新接口的测试响应")
    public String getTestData() {
        return "Hello from new package!";
    }
}

4. 验证JAX-RS应用的资源注册 #

如果项目里有自定义的Application类，要确保它注册了所有包下的REST资源：

import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
import java.util.HashSet;
import java.util.Set;

@ApplicationPath("/api")
public class RestApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<>();
        // 添加所有REST类，或确保包扫描覆盖到新包
        classes.add(HelloWorldEndpoint.class);
        classes.add(NewRestEndpoint.class);
        return classes;
    }
}

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