Spring Boot集成Swagger3后无法为基础URL追加/api前缀问题求助

配置存在的核心错误 #

• 路径处理逻辑完全颠倒：当前getOperationPath实现的作用是删除接口路径中的/api片段，和添加前缀的需求完全相反
• 接口实现不符合要求：直接实现PathProvider顶层接口且getResourceListingPath返回null，会导致Swagger资源路径解析异常，无法正确加载基础路径配置
• 未使用官方提供的简洁配置：SpringFox 3.0 已经内置了全局路径前缀配置API，不需要自定义PathProvider实现

正确配置方案 #

方案1：使用官方pathMapping配置（推荐，无需自定义Provider） #

SpringFox 3.0 提供了pathMapping方法直接配置全局接口前缀，是官方推荐的实现方式，配置成本最低。

依赖配置（保持和你当前的一致即可）

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

完整Swagger配置类

@Configuration
public class SwaggerConfig {
    // 此处省略你原有代码中profile、host、Logger的注入逻辑，保持你原有的注入方式即可
    @Bean
    public Docket api() {
        Docket docket = null;
        try{
            Docket docketBuilder = new Docket(DocumentationType.OAS_3) // 3.0推荐使用OAS_3规范，也可保留SWAGGER_2不影响功能
                    .host(host);
            // 非本地/测试环境添加/api前缀
            if(!(profile.contains("local") || profile.contains("test"))){
                docketBuilder = docketBuilder.pathMapping("/api");
            }
            docket = docketBuilder.select()
                    .apis(RequestHandlerSelectors.basePackage("org.app.controller"))
                    .paths(PathSelectors.any())
                    .build();
        }catch(Exception e){
            logger.info("Unable to return docket",e);
        }
        return docket;
    }
}

配置完成后重启服务，访问swagger-ui即可看到所有接口的基础路径自动添加/api前缀。

方案2：自定义PathProvider实现（特殊场景使用） #

如果必须通过自定义Provider实现路径逻辑，需要继承RelativePathProvider而非直接实现顶层PathProvider接口，同时不要返回null的资源路径：

// 首先注入ServletContext对象
@Autowired
private ServletContext servletContext;

// 构造Docket时的pathProvider配置
.pathProvider(new RelativePathProvider(servletContext){
    @Override
    public String getApplicationBasePath(){
        return "/api";
    }
})

额外注意事项 #

• 如果你的项目配置了server.servlet.context-path，注意前缀的拼接逻辑，避免出现重复前缀的问题
• SpringFox 3.0 默认的swagger-ui访问地址为http://{host}:{port}/{context-path}/swagger-ui/index.html，确认访问地址无误

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