Spring Boot 2.7下Spring与Jersey API的Swagger统一配置优化问询

我在Spring Boot 2.7版本的应用中，为Spring实现的私有API配置了Swagger，同时服务器上还有Jersey实现的公共API，也已配置Swagger并可正常访问。访问http://localhost:8080/@context.root@/swagger-ui/index.html能看到两个文档定义：

• "01 - public" -> /@context.root@/swagger-ui/pub/openapi.json
• "02 - private" -> /@context.root@/v3/api-docs/02 - private

但当前配置存在冗余，两者的openapi.json生成逻辑不同，我希望统一用GroupedOpenApi类配置Jersey公共API的Swagger，同时移除application.yml中的urls配置，但尝试后生成的公共API文档没有端点/操作，未能成功实现。计划下月升级至Spring Boot 3。

要实现统一用GroupedOpenApi管理Jersey公共API的Swagger，需要借助springdoc对Jersey的集成支持，具体步骤如下：

1. 添加springdoc-Jersey集成依赖 #

springdoc默认只支持Spring MVC控制器，要扫描Jersey资源类，需添加专门的集成依赖。修改pom.xml，新增以下依赖：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-jersey-core</artifactId>
    <version>1.6.2</version> <!-- 版本要和springdoc-openapi-ui保持一致 -->
</dependency>

2. 启用并配置公共API的GroupedOpenApi Bean #

在SwaggerConfiguration中取消注释publicApi Bean，并调整配置确保能识别Jersey资源：

@Bean
public GroupedOpenApi publicApi(final AppProperties properties) {
    return GroupedOpenApi.builder()
        .group("01 - public")
        .pathsToMatch("/api/pub/**")
        .packagesToScan("path.to.resources.package.api.pub") // 指定Jersey资源所在包
        .addOpenApiCustomiser(customizeApiPublic(properties))
        .build();
}

private OpenApiCustomiser customizeApiPublic(final AppProperties properties) {
    return (final OpenAPI openApi) -> openApi
        .addServersItem(new Server().url("/" + properties.getContextRoot() + "/api/pub"))
        .getInfo()
        .title("Public API title")
        .description("Public API description")
        .version(properties.getAppVersion());
}

3. 移除Jersey中原有Swagger配置 #

修改ApiPublicJerseyConfig，删除原有的Swagger注册代码，只保留Jersey资源包扫描：

public class ApiPublicJerseyConfig extends ResourceConfig {
    public ApiPublicJerseyConfig(AppProperties properties) {
        super();
        packages("path.to.resources.package.api.pub");
        // 移除原有的register(swaggerConfig(properties))相关代码
    }
}

4. 调整Jersey Servlet映射 #

修改AppConfiguration中的publicJersey Bean，去掉Swagger相关的URL映射，由springdoc统一处理：

@Bean
public ServletRegistrationBean<ServletContainer> publicJersey(AppProperties properties) 
{
    ServletRegistrationBean<ServletContainer> pubJersey = new ServletRegistrationBean<>(
         new ServletContainer(new ApiPublicJerseyConfig(properties)));
    pubJersey.addUrlMappings("/api/pub/*"); // 移除/swagger-ui/pub/*映射
    pubJersey.setLoadOnStartup(0);
    return pubJersey;
}

5. 清理application.yml配置 #

移除springdoc.swagger-ui.urls配置项，修改后的application.yml如下：

springdoc:
  swagger-ui:
    disable-swagger-default-url: true
    defaultModelExpandDepth: 3
    operationsSorter: "alpha"
    tagsSorter: "alpha"

原理说明 #

添加的springdoc-openapi-jersey-core依赖会自动注册Jersey资源扫描器，让springdoc能够识别Jersey的@Path、@GET等注解，生成符合OpenAPI规范的文档。此时两个API的文档都会通过springdoc的/v3/api-docs/{group-name}路径暴露，swagger-ui会自动加载所有GroupedOpenApi定义的分组。

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