加拿大机器人 C# SwaggerLoginAuthPlugin：Swagger文档登录认证插件开发指南

作者:admin | 分类:加拿大机器人 | 浏览:2 | 日期:2026年05月09日

一、插件开发背景与核心价值

在前后端分离的开发模式中，Swagger凭借自动生成接口文档、支持在线调试的能力，成为API开发团队

的必备工具。但默认情况下，Swagger UI无访问限制，任何知道地址的用户都能查看接口详情并发起调

试请求，存在数据泄露、非法调用的安全风险。

SwaggerLoginAuthPlugin正是为解决这一痛点而生的轻量级插件，它能快速为Swagger文档添加登录验

证页面，只有通过身份校验的用户才能进入接口文档页面，有效保护API接口的安全性，同时保留Swagger

原本的所有功能特性。

二、插件核心设计思路

（一）认证流程设计

插件采用拦截器模式，在Swagger UI请求链路中插入登录校验逻辑：

请求拦截：当用户访问Swagger UI页面时，插件自动拦截HTTP请求
凭证校验：检查请求中是否携带有效的登录凭证（如Cookie、JWT Token）
权限判断：验证凭证的合法性与有效性，判断用户是否具备访问权限
页面跳转：未登录用户自动重定向到自定义登录页面，登录成功后返回Swagger UI

（二）技术架构选型

基于ASP.NET Core中间件：完美适配.NET Core/.NET 5+生态系统
Cookie认证方案：使用ASP.NET Core内置的Cookie认证机制管理会话
自定义登录页面：支持开发者根据需求定制登录界面样式与逻辑
可扩展验证接口：预留外部验证接口，支持对接企业统一身份认证系统

三、插件详细实现步骤

（一）项目初始化

创建.NET类库项目，命名为SwaggerLoginAuthPlugin
添加必要的NuGet包依赖：
Install-Package Swashbuckle.AspNetCore.SwaggerUI Install-Package Microsoft.AspNetCore.Authentication.Cookies Install-Package Microsoft.AspNetCore.Mvc

（二）核心中间件实现

public class SwaggerLoginMiddleware { private readonly RequestDelegate _next; private readonly SwaggerLoginOptions _options; public SwaggerLoginMiddleware(RequestDelegate next, SwaggerLoginOptions options) { _next = next; _options = options; } public async Task InvokeAsync(HttpContext context) { // 检查是否为Swagger UI请求 if (context.Request.Path.StartsWithSegments(_options.SwaggerRoutePrefix)) { // 验证用户登录状态 if (!context.User.Identity.IsAuthenticated) { // 重定向到登录页面 context.Response.Redirect(_options.LoginPath); return; } // 检查用户权限（可扩展） if (!await _options.PermissionValidator(context.User)) { context.Response.StatusCode = StatusCodes.Status403Forbidden; await context.Response.WriteAsync("无访问权限"); return; } } await _next(context); } }

（三）登录页面与认证逻辑

登录页面组件：创建嵌入式Razor视图作为默认登录页面，支持自定义样式
认证控制器：实现登录接口，处理用户凭证验证与会话创建

[ApiController] [Route("[controller]")] public class SwaggerAuthController : ControllerBase { private readonly IConfiguration _configuration; public SwaggerAuthController(IConfiguration configuration) { _configuration = configuration; } [HttpPost("login")] public async Task<IActionResult> Login([FromForm] LoginRequest request) { // 验证用户凭证（此处可替换为实际业务逻辑） var validUser = _configuration["SwaggerAuth:Username"] == request.Username && _configuration["SwaggerAuth:Password"] == request.Password; if (!validUser) { return BadRequest("用户名或密码错误"); } // 创建登录凭证 var claims = new List<Claim> { new Claim(ClaimTypes.Name, request.Username), new Claim(ClaimTypes.Role, "SwaggerUser") }; var claimsIdentity = new ClaimsIdentity(claims, CookieAuthenticationDefaults.AuthenticationScheme); var authProperties = new AuthenticationProperties { IsPersistent = request.RememberMe, ExpiresUtc = DateTimeOffset.UtcNow.AddHours(2) }; await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity), authProperties); return Redirect("/swagger"); } }

（四）插件扩展方法

public static class SwaggerLoginExtensions { public static IApplicationBuilder UseSwaggerLogin(this IApplicationBuilder app, Action<SwaggerLoginOptions> optionsAction = null) { var options = new SwaggerLoginOptions(); optionsAction?.Invoke(options); // 配置Cookie认证 app.UseAuthentication(); // 注册中间件 return app.UseMiddleware<SwaggerLoginMiddleware>(options); } public static IServiceCollection AddSwaggerLogin(this IServiceCollection services, IConfiguration configuration) { // 配置Cookie认证 services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie(options => { options.LoginPath = "/swaggerauth/login"; options.LogoutPath = "/swaggerauth/logout"; options.ExpireTimeSpan = TimeSpan.FromHours(2); }); // 添加认证控制器 services.AddControllers().AddApplicationPart(typeof(SwaggerAuthController).Assembly); return services; } }

四、插件使用指南

（一）快速集成步骤

安装插件：将编译后的DLL文件添加到项目引用，或通过NuGet安装
配置服务：在Program.cs中添加服务配置

builder.Services.AddSwaggerLogin(builder.Configuration); builder.Services.AddSwaggerGen(c => { c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" }); });

启用中间件：在请求管道中启用插件

app.UseSwaggerLogin(options => { options.SwaggerRoutePrefix = "/swagger"; options.LoginPath = "/swaggerauth/login"; options.PermissionValidator = async (user) => { // 自定义权限验证逻辑 return user.IsInRole("SwaggerUser"); }; }); app.UseSwagger(); app.UseSwaggerUI(c => { c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1"); });

配置认证信息：在appsettings.json中添加登录凭证

{ "SwaggerAuth": { "Username": "admin", "Password": "123456" } }

（二）高级配置选项

配置项	说明	默认值
SwaggerRoutePrefix	Swagger UI路由前缀	"/swagger"
LoginPath	登录页面路由	"/swaggerauth/login"
PermissionValidator	自定义权限验证委托	允许所有已登录用户
SessionTimeout	会话超时时间	2小时
EnablePersistentCookie	是否启用持久化Cookie	false

五、插件扩展功能

（一）自定义登录页面

开发者可以通过以下方式替换默认登录页面：

创建自定义登录视图文件
在配置中指定自定义登录页面路径

app.UseSwaggerLogin(options => { options.LoginPath = "/custom-swagger-login"; });

实现对应的控制器动作返回自定义视图

（二）对接统一身份认证

插件支持对接企业级身份认证系统：

options.PermissionValidator = async (user) => { // 调用企业认证API验证用户权限 var authService = context.RequestServices.GetRequiredService<IEnterpriseAuthService>(); return await authService.ValidateSwaggerAccess(user.Identity.Name); };

（三）添加IP白名单

可以结合IP限制中间件，为Swagger UI添加IP访问控制：

options.PermissionValidator = async (user) => { var remoteIp = context.Connection.RemoteIpAddress; var allowedIps = new List<IPAddress> { IPAddress.Parse("192.168.1.100") }; return allowedIps.Contains(remoteIp) && user.IsInRole("SwaggerUser"); };