ASP.NET Core中Swagger集成Google认证接口调用失败问题

问题场景 #

已完成ASP.NET Core API的Google OAuth认证集成与Swagger配置：

• 成功通过Swagger的「Authorize」按钮完成Google登录授权
• 直接在地址栏访问受保护API可正常授权并返回结果
• 但在Swagger页面点击「Execute」调用API时返回“Undocumented”

核心原因 #

1. Swagger UI默认不会自动将认证后的Cookie携带到API请求中，而当前认证方案依赖Cookie作为默认Scheme
2. OAuth2授权码流程未启用PKCE，不符合Google OAuth的推荐流程要求
3. Cookie的SameSite属性配置可能阻止浏览器在Swagger请求中携带Cookie

具体修复方案 #

1. 启用Swagger UI的PKCE模式 #

在Swagger UI配置中添加PKCE启用项，适配Google OAuth的流程要求：

options.OAuthAppName(GoogleDefaults.DisplayName);
options.OAuthClientId(configuration[GoogleOAuthSettings.ClientIdName]!);
options.OAuthClientSecret(configuration[GoogleOAuthSettings.ClientSecretName]!);
options.OAuthScopes([.. GoogleOAuthSettings.Scopes.Keys]);
options.OAuthUsePkce(); // 新增此行，启用PKCE模式

2. 配置Swagger UI自动携带Cookie #

通过注入请求拦截器，让Swagger请求自动携带认证Cookie：

options.UseRequestInterceptor("(request) => { document.cookie.split(';').forEach(cookie => { const [name, value] = cookie.split('=').map(c => c.trim()); request.headers.append('Cookie', `${name}=${value}`); }); return request; }");

3. 调整Cookie认证的SameSite与安全策略 #

修改AddCookie的配置，确保Cookie可被Swagger请求正常携带：

builder.Services
    .AddAuthentication()
    .AddCookie(options =>
    {
        options.Cookie.SameSite = SameSiteMode.Lax; // 非HTTPS环境用Lax，HTTPS环境可设为None
        options.Cookie.SecurePolicy = CookieSecurePolicy.Always; // HTTPS环境强制启用安全Cookie
        options.Events.OnRedirectToLogin = context =>
        {
            // 避免Swagger请求被重定向到登录页，直接返回401状态码
            context.Response.StatusCode = StatusCodes.Status401Unauthorized;
            return Task.CompletedTask;
        };
    })
    .AddGoogle();

4. 确认中间件顺序正确 #

确保Program.cs中的中间件顺序符合认证授权逻辑：

app.UseHttpsRedirection();
app.UseAuthentication(); // 认证中间件必须在授权中间件之前
app.UseAuthorization();

// Swagger相关中间件放在认证授权之后
app.UseSwagger();
app.UseSwaggerUI(options =>
{
    // 你的Swagger UI配置
});

5. 校验SecurityDefinition名称一致性 #

确保SwaggerGen配置中的SecurityDefinitionName与AuthorizationOperationFilter中的常量完全一致（当前代码中均为"google_auth"，若存在拼写错误需修正）。

验证方法 #

1. 重启API服务，重新完成Swagger授权流程
2. 调用API时打开浏览器开发者工具的Network标签，检查请求头是否包含Cookie字段
3. 查看API日志，确认认证中间件是否正确处理请求

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