Springdoc自定义Swagger静态资源时仅index.html被处理的问题求助

我之前也碰到过一模一样的情况，其实问题出在SwaggerIndexPageTransformer的设计定位上——它本来就只负责处理index.html这个入口页面，像js、css、图片这类其他Swagger静态资源，根本不会走这个Transformer的处理链路。这是Springdoc默认的配置逻辑导致的，并不是你的代码写错了。

为什么会出现这种情况？ #

Springdoc在注册Swagger相关静态资源时，对index.html和其他WebJar资源的处理路径是分开的：

• SwaggerIndexPageTransformer是专门绑定到/swagger-ui/index.html（或你自定义的路径）的专属处理逻辑；
• 而swagger-ui.css、swagger-ui-bundle.js这类资源，是直接从WebJar的META-INF/resources/webjars/swagger-ui/路径下直接对外提供的，完全不会经过这个Transformer。

正确的自定义方案 #

如果要覆盖所有Swagger静态资源的处理，你需要自定义一个通用的ResourceTransformer，并把它注册到Spring的资源处理链中，而不是只依赖SwaggerIndexPageTransformer。具体步骤如下：

1. 编写自定义的ResourceTransformer：

import org.springframework.core.io.ByteArrayResource;
import org.springframework.core.io.Resource;
import org.springframework.web.servlet.resource.ResourceTransformer;
import org.springframework.web.servlet.resource.ResourceTransformerChain;
import javax.servlet.http.HttpServletRequest;
import java.io.IOException;

public class CustomSwaggerResourceTransformer implements ResourceTransformer {

    @Override
    public Resource transform(HttpServletRequest request, Resource resource, ResourceTransformerChain chain) throws IOException {
        Resource transformedResource = chain.transform(request, resource);
        String resourcePath = transformedResource.getURL().toString();

        // 处理swagger-ui.css，示例：修改页面背景色
        if (resourcePath.contains("swagger-ui.css")) {
            String cssContent = new String(transformedResource.getInputStream().readAllBytes());
            cssContent = cssContent.replace("body {", "body { background-color: #f5f5f5; ");
            return new ByteArrayResource(cssContent.getBytes());
        }

        // 处理swagger-ui-bundle.js，示例：替换某个默认配置
        if (resourcePath.contains("swagger-ui-bundle.js")) {
            String jsContent = new String(transformedResource.getInputStream().readAllBytes());
            jsContent = jsContent.replace("defaultModelsExpandDepth: 1", "defaultModelsExpandDepth: 0");
            return new ByteArrayResource(jsContent.getBytes());
        }

        // 处理其他资源，比如图片、map文件等
        if (resourcePath.contains("favicon-32x32.png")) {
            // 替换自定义图标逻辑
        }

        return transformedResource;
    }
}

2. 把这个Transformer注册到Spring的资源处理配置里：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcSwaggerConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/swagger-ui/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/swagger-ui/")
                .resourceChain(true)
                .addTransformer(new CustomSwaggerResourceTransformer());
    }
}

额外注意点 #

• 确保你的Spring版本和Springdoc版本兼容，不同版本的WebJar资源路径可能有细微差别；
• 如果还需要处理index.html，可以把原来SwaggerIndexPageTransformer中的逻辑合并到这个自定义Transformer里，这样一套逻辑就能覆盖所有资源；
• 对于.map这类源映射文件，除非你需要修改源映射内容，否则一般不需要处理，保持默认即可。

这样配置完成后，所有通过/swagger-ui/**路径访问的静态资源都会经过你的自定义Transformer处理，就能覆盖你提到的所有目标文件了。

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