Apache Wicket 6.x项目结合wicketstuff-rest如何配置Swagger UI自动生成接口文档？

该方案无需使用swagger2markup，直接通过Swagger原生注解+静态资源部署即可实现接口文档自动同步，适配Wicket 6.x版本环境。

前置依赖准备 #

• 保留原有适配Wicket 6.x的wicketstuff-rest相关依赖
• 新增Swagger 1.5.x版本核心依赖，该版本兼容JDK 7+，适配Wicket 6运行环境，依赖坐标为 io.swagger:swagger-core:1.5.24
• 无需引入额外的文档转换依赖

配置步骤 #

1. 给REST接口添加Swagger注解 #

在原有wicketstuff-rest实现的接口类、方法、参数上直接添加Swagger标准注解即可，示例如下：

// 接口类添加模块注解
@Api(value = "用户操作接口", tags = "用户管理")
public class UserRestResource extends AbstractRestResource {
    // 接口方法添加功能说明
    @ApiOperation(value = "查询用户详情", notes = "根据用户ID查询单个用户信息")
    @ApiResponses(value = {
        @ApiResponse(code = 200, message = "查询成功"),
        @ApiResponse(code = 404, message = "用户不存在")
    })
    // 参数添加说明
    public UserVO getUser(@ApiParam(value = "用户ID", required = true) @PathParam("id") String id) {
        // 原有业务逻辑无需修改
    }
}

2. 初始化Swagger扫描配置 #

在Wicket应用入口类的init()方法中添加Swagger全局配置，指定接口扫描范围和服务基础信息：

@Override
public void init() {
    super.init();
    // 原有Wicket配置、REST接口注册逻辑全部保留
    
    // 新增Swagger配置
    BeanConfig beanConfig = new BeanConfig();
    beanConfig.setVersion("你的接口版本号，如1.0.0");
    beanConfig.setTitle("你的项目API文档名称");
    beanConfig.setDescription("接口文档描述");
    beanConfig.setSchemes(new String[]{"http", "https"});
    beanConfig.setHost("你的接口服务域名:端口");
    beanConfig.setBasePath("/你的项目上下文路径，没有则留空");
    beanConfig.setResourcePackage("你的REST接口所在的包路径，多个包用逗号分隔");
    beanConfig.setScan(true);
}

3. 注册Swagger元数据接口 #

将Swagger的接口元数据查询能力注册到Wicket的资源池中，对外暴露swagger.json接口供UI读取：

// 同上在init()方法的REST资源注册部分添加
mountResource("/swagger.json", new ResourceReference("swaggerJson") {
    @Override
    public IResource getResource() {
        return new ApiListingResource();
    }
});
// 注册Swagger序列化适配组件
addComponentInstantiationListener(new SwaggerComponentInjector(this));

4. 部署Swagger UI静态资源 #

下载Swagger UI 3.x的静态资源包，解压后放入项目webapp目录下的static/swagger-ui路径中，修改资源包内index.html中的默认请求地址，改为你上一步注册的swagger.json访问路径，示例：

// 原index.html中的url配置修改为
url: "/你的项目上下文路径/swagger.json"

最后在Wicket的安全拦截配置中，将/swagger.json和/static/swagger-ui/**路径加入白名单，避免被权限校验拦截。

验证使用 #

启动项目后访问 http://你的服务地址/项目上下文路径/static/swagger-ui/index.html 即可查看自动生成的可视化接口文档，接口新增、参数变更时只需要更新对应Swagger注解，重启服务后文档自动同步，无需手动修改。

注意事项 #

• 不要使用2.x及以上版本的Swagger，会出现JDK版本不兼容、类加载冲突问题
• wicketstuff-rest的路径参数、请求参数注解要和@ApiParam的配置对应，避免UI识别参数错误
• 如果需要接口文档权限控制，可以自行给swagger.json和swagger-ui路径添加访问校验逻辑

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