如何将Spring Boot中Swagger UI部署到/swagger/路径下？

问题分析 #

当前api-docs已成功迁移至/swagger/api-docs，但swagger-ui.html仍只能在根路径访问，核心原因是：

1. SpringFox 2.8.0对Swagger UI的路径配置逻辑与高版本不同，base-url配置不生效
2. Swagger UI静态页面默认引用根路径下的webjars资源，直接修改资源映射会导致加载失败
3. 错误的pathMapping配置会干扰API接口路径

分步解决方案 #

1. 修正application.yml配置 #

SpringFox 2.8.0中需使用path字段配置Swagger UI的访问路径，而非base-url：

springfox:
  documentation:
    swagger:
      v2:
        path: /swagger/api-docs
    swagger-ui:
      path: /swagger/swagger-ui.html

2. 调整WebAppConfig资源映射 #

配置/swagger路径下的资源映射，同时可选添加根路径重定向逻辑：

@Configuration
@EnableWebMvc
public class WebAppConfig extends WebMvcConfigurerAdapter {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 映射/swagger下的swagger-ui.html
        registry.addResourceHandler("/swagger/swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        // 映射/swagger下的webjars资源
        registry.addResourceHandler("/swagger/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/");
        
        // 可选：将根路径的swagger-ui.html重定向到/swagger路径
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/")
                .resourceChain(false)
                .addResolver(new RedirectResourceResolver() {
                    @Override
                    protected String getUrlPath(HttpServletRequest request, String resourcePath,
                                                ResourceResolverChain chain) {
                        return "/swagger/swagger-ui.html";
                    }
                });
    }
}

3. 修正SpringFoxConfig配置 #

移除pathMapping("/swagger")，避免给业务API接口添加不必要的前缀：

@Configuration
@EnableSwagger2
@Profile({"!prod && swagger"})
public class SpringFoxConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("OUR-API")
                .description("our api service endpoints")
                .version("mixed")
                .build();
    }
}

4. 修复Swagger UI资源引用路径（关键） #

添加UiConfiguration配置，让Swagger UI自动将所有资源引用前缀改为/swagger：

@Configuration
public class SwaggerUiCustomConfig {

    @Bean
    public UiConfiguration uiConfiguration() {
        return UiConfigurationBuilder.builder()
                .baseUrl("/swagger")
                .build();
    }
}

验证结果 #

完成配置后：

• 访问https://myservice.com/swagger/swagger-ui.html可正常打开Swagger UI
• 根路径https://myservice.com/swagger-ui.html会自动重定向到/swagger路径（若开启重定向）
• https://myservice.com/swagger/api-docs可正常访问接口文档

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