NSwag中实现Swagger UI请求头自动注入XSRF令牌的解决方案

背景介绍

在ASP.NET Core Web API开发中，跨站请求伪造(CSRF/XSRF)防护是一个重要的安全考虑。许多开发者会使用Antiforgery中间件来生成和验证XSRF令牌。当通过Swagger UI测试这些受保护的API时，如何自动将XSRF令牌注入请求头成为一个常见需求。

传统Swashbuckle解决方案

在使用Swashbuckle(Swashbuckle.AspNetCore)时，开发者通常会利用UseRequestInterceptor功能来实现这一需求。该方法允许在发送请求前执行JavaScript代码，从cookie中提取XSRF令牌并添加到请求头中。典型实现如下：

(request) => { 
    var cv = document.cookie.split('; ')
        .filter(row => row.startsWith('XSRF-TOKEN='))
        .map(c => c.split('=')[1])[0]; 
    request.headers['X-XSRF-TOKEN'] = cv; 
    return request; 
}

NSwag中的实现挑战

当从Swashbuckle迁移到NSwag时，开发者发现NSwag没有直接等效的UseRequestInterceptor功能。虽然NSwag提供了IOperationProcessor接口，但它主要用于服务端操作处理，无法直接解决客户端请求拦截的需求。

NSwag解决方案

经过探索，发现可以通过以下方式在NSwag中实现相同的功能：

1. 使用CustomHeadContent注入自定义脚本： 在Swagger UI配置中，通过CustomHeadContent属性注入自定义JavaScript文件：

app.UseSwaggerUi(c => {
    c.CustomHeadContent = @"<script src='./Scripts/AntiForgery.js' charset='UTF-8'></script>";
});

2. 创建自定义JavaScript文件： 在项目中创建一个JavaScript文件(如AntiForgery.js)，重写window.fetch方法：

// 保存原始的fetch方法
const originalFetch = window.fetch;

// 重写fetch方法
window.fetch = function(input, init) {
    // 从cookie中获取XSRF令牌
    const xsrfToken = document.cookie.split('; ')
        .find(row => row.trim().startsWith('XSRF-TOKEN='))
        ?.split('=')[1];
    
    // 确保init对象存在
    init = init || {};
    
    // 设置请求头
    init.headers = init.headers || {};
    if (xsrfToken) {
        init.headers['X-XSRF-TOKEN'] = xsrfToken;
    }
    
    // 调用原始fetch方法
    return originalFetch(input, init);
};

实现原理

这种方法利用了JavaScript的原型继承特性，通过以下步骤工作：

1. 保存原始的window.fetch方法引用
2. 用自定义实现覆盖window.fetch
3. 在自定义实现中：
   • 从cookie中提取XSRF令牌
   • 确保请求配置对象存在
   • 添加XSRF令牌到请求头
   • 调用原始fetch方法完成请求

由于Swagger UI内部使用fetch API进行请求，这种覆盖方法能够拦截所有从Swagger UI发出的API请求，并自动添加必要的安全头。

优势与注意事项

这种解决方案有以下优势：

• 无需修改NSwag核心代码
• 保持Swagger UI的标准界面
• 灵活可配置，可以轻松添加其他全局请求处理逻辑

需要注意：

• 确保JavaScript文件路径配置正确
• 考虑浏览器兼容性(现代浏览器都支持fetch API)
• 在生产环境中确保脚本被正确压缩和缓存

结论

通过这种自定义脚本注入的方式，NSwag用户可以实现与Swashbuckle中UseRequestInterceptor类似的功能，为受XSRF保护的API提供便捷的Swagger UI测试支持。这种方法展示了NSwag的灵活性，同时也保持了解决方案的简洁性和可维护性。