如何让swagger-jaxrs2忽略API路径的内部隐藏前缀？

针对你遇到的问题（内部API路径带/publicApi前缀，但对外需要隐藏），可以通过两种方式实现swagger-jaxrs2（v2.2.7）生成的OpenAPI文档去掉该前缀：

方法一：自定义PathProvider #

Swagger的PathProvider负责解析API路径，我们可以重写它的路径处理逻辑，自动移除内部前缀：

1. 实现自定义PathProvider类

import io.swagger.jaxrs.DefaultPathProvider;

public class CustomApiPathProvider extends DefaultPathProvider {
    private static final String INTERNAL_PREFIX = "/publicApi";

    @Override
    public String getOperationPath(String path) {
        String resolvedPath = super.getOperationPath(path);
        // 移除内部前缀，保留后续路径
        if (resolvedPath.startsWith(INTERNAL_PREFIX)) {
            return resolvedPath.substring(INTERNAL_PREFIX.length());
        }
        return resolvedPath;
    }
}

2. 注册自定义PathProvider

• 若使用web.xml配置：

<servlet>
    <servlet-name>SwaggerConfig</servlet-name>
    <servlet-class>io.swagger.jaxrs.config.DefaultJerseyJaxrsConfig</servlet-class>
    <init-param>
        <param-name>swagger.path.provider</param-name>
        <param-value>你的包路径.CustomApiPathProvider</param-value>
    </init-param>
    <!-- 其他Swagger配置（如resourcePackage、basePath等） -->
</servlet>

• 若使用Java代码配置（Jersey ResourceConfig）：

import io.swagger.jaxrs.config.BeanConfig;

public class ApiResourceConfig extends ResourceConfig {
    public ApiResourceConfig() {
        // 注册你的API资源类
        register(PublicApiFooResource.class);

        BeanConfig swaggerConfig = new BeanConfig();
        swaggerConfig.setPathProviderClass(CustomApiPathProvider.class);
        swaggerConfig.setBasePath("/"); // 对外API的根路径
        swaggerConfig.setResourcePackage("你的API接口所在包");
        swaggerConfig.setScan(true);
    }
}

方法二：通过OpenAPIFilter修改生成的文档 #

如果自定义PathProvider不符合你的场景，可以在OpenAPI文档生成后，手动遍历路径并移除前缀：

1. 实现OpenAPIFilter类

import io.swagger.models.OpenAPI;
import io.swagger.models.Path;
import io.swagger.jaxrs.filter.OpenAPIFilter;
import io.swagger.jaxrs.model.ReaderContext;

import java.util.HashMap;
import java.util.Map;

public class PathPrefixRemovalFilter implements OpenAPIFilter {
    private static final String INTERNAL_PREFIX = "/publicApi";

    @Override
    public void filterOpenAPI(OpenAPI openAPI) {
        Map<String, Path> cleanedPaths = new HashMap<>();
        // 遍历所有路径，替换内部前缀
        for (Map.Entry<String, Path> entry : openAPI.getPaths().entrySet()) {
            String originalPath = entry.getKey();
            String newPath = originalPath.startsWith(INTERNAL_PREFIX) 
                ? originalPath.substring(INTERNAL_PREFIX.length()) 
                : originalPath;
            cleanedPaths.put(newPath, entry.getValue());
        }
        openAPI.setPaths(cleanedPaths);
    }

    // 其他接口方法默认实现
    @Override
    public boolean isFiltered(String method, String path, String methodName, Class<?> cls) {
        return false;
    }

    @Override
    public void filterReaderContext(ReaderContext readerContext) {}
}

2. 注册过滤器

• web.xml配置：

<init-param>
    <param-name>swagger.filter</param-name>
    <param-value>你的包路径.PathPrefixRemovalFilter</param-value>
</init-param>

• Java代码配置：

swaggerConfig.setFilterClass(PathPrefixRemovalFilter.class);

两种方法都能让生成的OpenAPI文档中，原本的/publicApi/foo路径变为对外展示的/foo，避免内部转发逻辑泄露。

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