嵌入式Jetty的Maven项目JAX-RS API集成Swagger文档配置问询

嘿，我来帮你把剩下的Swagger配置补全！既然你已经搭好了SwaggerServlet的架子，咱们一步步来完成整个流程：

1. 补全Maven依赖 #

首先得确保你的pom.xml里加了Swagger和JAX-RS整合的必要依赖，还有Swagger UI的资源包（用WebJars最方便）：

<!-- Swagger JAX-RS 核心整合依赖 -->
<dependency>
    <groupId>io.swagger</groupId>
    <artifactId>swagger-jaxrs</artifactId>
    <version>1.6.12</version> <!-- 选稳定版本，这个和多数JAX-RS实现兼容 -->
</dependency>
<!-- WebJars版Swagger UI，方便静态资源管理 -->
<dependency>
    <groupId>org.webjars</groupId>
    <artifactId>swagger-ui</artifactId>
    <version>4.18.3</version> <!-- 对应版本要和swagger-core匹配 -->
</dependency>

2. 完善SwaggerServlet的BeanConfig配置 #

这是Swagger扫描API的核心配置，把你的BeanConfig补全，指定扫描包、API元信息和访问路径：

@WebServlet(name = "SwaggerConfig", loadOnStartup = 1) // 加loadOnStartup让服务器启动就初始化
public class SwaggerServlet extends HttpServlet {
    @Override
    public void init(ServletConfig config) throws ServletException {
        super.init(config);
        System.out.println("init SwaggerServlet");
        
        BeanConfig beanConfig = new BeanConfig();
        // 替换成你实际的API资源类所在包，Swagger会扫描这个包下的JAX-RS注解
        beanConfig.setResourcePackage("com.yourcompany.yourproject.api");
        // 设置API的基本信息，会显示在Swagger UI里
        beanConfig.setTitle("你的项目API文档");
        beanConfig.setDescription("基于嵌入式Jetty+JAX-RS的后端API接口文档");
        beanConfig.setVersion("1.0.0");
        // 这里要和你的JAX-RS应用根路径一致，比如你的API都是/api开头就填这个
        beanConfig.setBasePath("/api");
        // 启用扫描功能
        beanConfig.setScan(true);
        // 让生成的swagger.json格式更易读
        beanConfig.setPrettyPrint(true);
    }
}

3. 注册Swagger的JAX-RS资源 #

你的JAX-RS应用类（继承Application的那个）需要注册Swagger自带的资源类，这样才能对外提供swagger.json接口：

public class YourJaxRsApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<>();
        // 先注册你自己的API资源类
        classes.add(UserApi.class);
        classes.add(OrderApi.class);
        // 注册Swagger的核心资源，用来生成swagger.json
        classes.add(ApiListingResource.class);
        classes.add(SwaggerSerializers.class);
        return classes;
    }
}

4. 配置嵌入式Jetty的Swagger UI访问 #

因为是嵌入式Jetty，得把Swagger UI的静态资源（通过WebJars引入的）部署到服务器里，在你的Jetty启动代码里加这段配置：

// 假设你已经初始化了Jetty Server实例
Server server = new Server(8080);

// 创建上下文
ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
context.setContextPath("/");
server.setHandler(context);

// 注册你的JAX-RS应用（以Jersey的ServletContainer为例）
ServletHolder jerseyServlet = context.addServlet(ServletContainer.class, "/api/*");
jerseyServlet.setInitParameter("javax.ws.rs.Application", "com.yourcompany.yourproject.YourJaxRsApplication");

// 注册SwaggerConfig Servlet
context.addServlet(SwaggerServlet.class, "/swagger-config");

// 配置WebJars资源访问，让Swagger UI能加载静态文件
ServletHolder webjarsServlet = context.addServlet(DefaultServlet.class, "/webjars/*");
webjarsServlet.setInitParameter("resourceBase", "META-INF/resources/webjars");
webjarsServlet.setInitParameter("dirAllowed", "false");

// 启动服务器
server.start();
server.join();

5. 给API添加Swagger注解（关键！） #

光配置还不够，得给你的JAX-RS资源类和方法加Swagger注解，这样生成的文档才会有详细的描述：

@Path("/users")
@Api(tags = "用户管理API") // 给这个资源类打标签，方便UI分类
public class UserApi {

    @GET
    @Path("/{userId}")
    @Produces(MediaType.APPLICATION_JSON)
    @ApiOperation(value = "根据ID获取用户信息", notes = "传入用户ID，返回该用户的完整详情")
    public User getUser(
        @ApiParam(value = "用户唯一ID", required = true) @PathParam("userId") Long userId
    ) {
        // 你的业务逻辑代码
        return new User(userId, "张三", "zhangsan@example.com");
    }
}

6. 测试验证 #

启动Jetty服务器后，先访问http://localhost:8080/api/swagger.json，如果能正常返回结构化的JSON，说明Swagger已经成功扫描到你的API了。

然后访问Swagger UI地址：http://localhost:8080/webjars/swagger-ui/4.18.3/index.html?url=http://localhost:8080/api/swagger.json，就能看到可视化的API文档，还能直接在线测试接口！

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