JBoss EAP 7.4中EAR包RESTEasy API集成Swagger-UI自动检测方案咨询

核心结论 #

• 无需手动编写swagger.json，也不用将EAR转成WAR，只需给EAR中的REST模块添加Swagger/OpenAPI扩展依赖并做简单配置，就能自动生成API文档。
• 不需要swagger-codegen或swagger-inspector，仅靠RESTEasy的Swagger/OpenAPI扩展+已部署的swagger-ui即可实现。

具体操作步骤 #

1. 给EAR中的REST模块添加依赖 #

你的服务部署在JBoss EAP 7.4，它自带RESTEasy 3.x，推荐使用RESTEasy官方的OpenAPI扩展（和EAP兼容性更好），也可选择Swagger原生的JAX-RS注解扩展：

选项A：使用RESTEasy OpenAPI扩展（推荐）

在REST模块的pom.xml（Maven项目）中添加依赖：

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-openapi</artifactId>
    <version>3.17.0.Final</version> <!-- 对应EAP7.4的适配版本，可按需调整 -->
    <scope>provided</scope> <!-- 若EAP服务器已包含该类库则用provided，否则改为compile打包进模块 -->
</dependency>

选项B：使用Swagger JAX-RS2扩展

如果更习惯Swagger原生注解，添加以下依赖：

<dependency>
    <groupId>io.swagger.core.v3</groupId>
    <artifactId>swagger-jaxrs2</artifactId>
    <version>2.2.15</version> <!-- 选择兼容RESTEasy 3.x的版本 -->
    <scope>compile</scope>
</dependency>

2. 配置API文档生成 #

针对RESTEasy OpenAPI扩展

在你的REST应用类（继承Application的类）上添加注解配置基本信息：

import org.eclipse.microprofile.openapi.annotations.OpenAPIDefinition;
import org.eclipse.microprofile.openapi.annotations.info.Info;
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;

@ApplicationPath("/api")
@OpenAPIDefinition(
    info = @Info(
        title = "你的REST API文档",
        version = "1.0.0",
        description = "供外部模块开发者测试的API集合"
    )
)
public class MyRestApplication extends Application {
    // 空实现即可，或按需添加资源类注册逻辑
}

部署后，访问http://<EAP服务器地址>:<端口>/<EAR上下文根>/api/openapi.json就能获取自动生成的OpenAPI文档（即swagger-ui所需的数据源文件）。

针对Swagger JAX-RS2扩展

需要在REST应用类中注册Swagger的OpenAPI资源：

import io.swagger.v3.jaxrs2.integration.resources.OpenApiResource;
import javax.ws.rs.ApplicationPath;
import javax.ws.rs.core.Application;
import java.util.HashSet;
import java.util.Set;

@ApplicationPath("/api")
public class MyRestApplication extends Application {
    @Override
    public Set<Class<?>> getClasses() {
        Set<Class<?>> classes = new HashSet<>();
        // 注册你的所有REST资源类
        classes.add(UserResource.class);
        classes.add(OrderResource.class);
        // 注册Swagger的OpenAPI资源
        classes.add(OpenApiResource.class);
        return classes;
    }
}

部署后，同样通过http://<EAP服务器地址>:<端口>/<EAR上下文根>/api/openapi.json获取自动生成的文档。

3. 配置swagger-ui指向自动生成的文档 #

打开你部署在Undertow上的swagger-ui的index.html，找到url参数，替换为上述openapi.json的访问地址：

<script>
window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "http://<EAP服务器地址>:<端口>/<EAR上下文根>/api/openapi.json", // 替换为你的实际地址
    dom_id: '#swagger-ui',
    // 保留原有其他配置
  })
}
</script>

刷新swagger-ui页面，就能看到自动检测到的所有API接口，可直接在线测试。

关键注意事项 #

• 如果EAR中的REST模块是独立JAR（打包在EAR的lib目录），确保依赖正确打包，或确认EAP服务器已包含对应类库。
• 检查EAP的standalone.xml/domain.xml，RESTEasy扩展在EAP7.4中默认已启用，无需额外配置。
• 若遇到访问权限问题，需调整EAP的安全配置或REST模块的web.xml，确保openapi.json路径允许外部访问。

内容的提问来源于stack exchange，提问作者Fish-Guts