.NET Core（net7.0）自定义Swagger UI opsFilter插件不生效问题

核心问题原因 #

通过InjectJavascript引入的自定义脚本未生效，通常是因为脚本执行时机早于Swagger UI初始化，或者没有正确覆盖默认的opsFilter配置。

可行解决方案 #

1. 调整脚本注入时机与写法 #

确保脚本在Swagger UI的window.ui对象初始化完成后，再修改opsFilter。可以通过DOM监听或MutationObserver实现：

首先在Program.cs中配置注入：

builder.Services.AddSwaggerGen(c =>
{
    // 你的Swagger基础配置（如文档信息、注释等）
});

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.InjectJavascript("/swagger-custom-filter.js");
    // 其他UI配置（如默认文档、路由前缀等）
});

然后在wwwroot/swagger-custom-filter.js中编写自定义逻辑：

document.addEventListener('DOMContentLoaded', function() {
    // 监听Swagger UI元素加载，确保window.ui存在
    const observer = new MutationObserver(function(mutations) {
        const swaggerUi = window.ui;
        if (swaggerUi) {
            // 覆盖默认的opsFilter，实现不区分大小写的多维度筛选
            swaggerUi.getConfigs().opsFilter = function(taggedOps, phrase) {
                if (!phrase) return taggedOps;
                const lowerPhrase = phrase.toLowerCase();
                return taggedOps.filter(op => {
                    // 匹配标签、接口路径、摘要
                    const tagMatch = op.tags.some(tag => tag.toLowerCase().includes(lowerPhrase));
                    const pathMatch = op.path.toLowerCase().includes(lowerPhrase);
                    const summaryMatch = op.summary?.toLowerCase().includes(lowerPhrase) || false;
                    return tagMatch || pathMatch || summaryMatch;
                });
            };
            observer.disconnect(); // 完成后停止监听
        }
    });

    observer.observe(document.body, { childList: true, subtree: true });
});

2. 内联脚本注入（无需单独文件） #

如果不想维护单独的JS文件，可直接在UseSwaggerUI中嵌入内联脚本：

app.UseSwaggerUI(c =>
{
    c.InjectJavascript(string.Empty, @"
        document.addEventListener('DOMContentLoaded', function() {
            const observer = new MutationObserver(function(mutations) {
                const swaggerUi = window.ui;
                if (swaggerUi) {
                    swaggerUi.getConfigs().opsFilter = function(taggedOps, phrase) {
                        if (!phrase) return taggedOps;
                        const lowerPhrase = phrase.toLowerCase();
                        return taggedOps.filter(op => {
                            return op.tags.some(tag => tag.toLowerCase().includes(lowerPhrase)) ||
                                   op.path.toLowerCase().includes(lowerPhrase) ||
                                   (op.summary && op.summary.toLowerCase().includes(lowerPhrase));
                        });
                    };
                    observer.disconnect();
                }
            });
            observer.observe(document.body, { childList: true, subtree: true });
        });
    ");
});

3. 用配置扩展类统一管理 #

通过实现IConfigureOptions<SwaggerUIOptions>，更规范地管理UI配置：

public class SwaggerUIConfig : IConfigureOptions<SwaggerUIOptions>
{
    public void Configure(SwaggerUIOptions options)
    {
        options.InjectJavascript("/swagger-custom-filter.js");
        // 其他统一配置（如默认展开标签、OAuth设置等）
    }
}

// 在Program.cs中注册
builder.Services.ConfigureOptions<SwaggerUIConfig>();

关键注意事项 #

• 脚本路径要正确：wwwroot下的文件需以/开头，避免相对路径导致404。
• 测试前清空浏览器缓存：防止旧脚本残留导致不生效。
• 筛选逻辑可按需扩展：除标签外，还可匹配接口描述、请求方法等字段。

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