.NET Core 中 Swagger 配置详解：常用配置与实战技巧
随着微服务架构和 RESTful API 的广泛应用，API 文档的管理和自动化生成成为了开发中的重要部分。Swagger（现为 OpenAPI）是一款功能强大的工具，它可以自动生成 API 文档，并提供交互式 UI，帮助开发者、测试人员、前端开发人员等更高效地使用和测试 API。在 .NET Core 中，Swagger 的集成和配置非常简便，通过 Swashbuckle.AspNetCore 包，我们能够轻松地实现 API 文档的自动生成与展示。
本文将围绕 .NET Core 中 Swagger 的常用配置 进行详细讲解，涵盖从基础配置到一些常见的高级定制，包括多版本支持、认证配置、隐藏 API、API 路径过滤等常见场景。希望通过本文，您能快速掌握如何在 .NET Core 中灵活地配置 Swagger。
1. 启用 Swagger 的基本功能
首先，创建一个新的 .NET Core 项目并安装 Swashbuckle.AspNetCore 包：
dotnet add package Swashbuckle.AspNetCore
安装完成后，我们需要在项目中配置 Swagger。通常的基础配置包含：
-
注册 Swagger 服务
-
启用 Swagger UI
配置代码：
var builder = WebApplication.CreateBuilder(args);// 注册 Swagger 服务
builder.Services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo{Title = "智慧OA系统 API",Version = "v1",Description = "这是智慧OA系统的 API 文档",});// 启用 XML 注释，Swagger 会展示注释内容var xmlFile = Path.Combine(AppContext.BaseDirectory, "智慧OA系统.xml");c.IncludeXmlComments(xmlFile);
});var app = builder.Build();// 启用 Swagger 和 Swagger UI
if (app.Environment.IsDevelopment())
{app.UseSwagger();app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系统 API v1");c.RoutePrefix = string.Empty; // 设置 Swagger UI 路径});
}app.MapControllers();
app.Run();
解析：
-
在
builder.Services.AddSwaggerGen中，我们定义了 API 的元数据，如标题、版本、描述等。 -
通过
app.UseSwagger()启用 Swagger，app.UseSwaggerUI()启用交互式 Swagger UI，方便开发者直接在浏览器中查看和测试 API。
2. 启用多版本 API 文档
在实际开发中，API 会随着时间的推移不断进行版本更新。为了方便管理，我们需要为不同版本的 API 提供独立的 Swagger 文档。例如，假设我们有 v1 和 v2 两个版本的 API。
配置代码：
builder.Services.AddSwaggerGen(c =>
{c.SwaggerDoc("v1", new OpenApiInfo { Title = "智慧OA系统 v1", Version = "v1" });c.SwaggerDoc("v2", new OpenApiInfo { Title = "智慧OA系统 v2", Version = "v2" });
});app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系统 v1");c.SwaggerEndpoint("/swagger/v2/swagger.json", "智慧OA系统 v2");
});
解析：
-
通过
AddSwaggerGen配置多个版本的 API 文档。 -
使用
UseSwaggerUI为每个版本提供独立的 Swagger 端点，允许前端开发人员选择需要使用的 API 版本。
3. API 安全性设置（JWT 认证）
在许多现代应用中，JWT（JSON Web Token）认证已成为一种常见的身份验证方式。通过 Swagger，我们可以让开发者方便地在 Swagger UI 中输入 JWT Token，从而测试需要认证的 API。
配置代码：
builder.Services.AddSwaggerGen(c =>
{c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme{In = ParameterLocation.Header,Name = "Authorization",Type = SecuritySchemeType.ApiKey,Scheme = "Bearer",BearerFormat = "JWT",Description = "请输入JWT Token进行认证"});c.AddSecurityRequirement(new OpenApiSecurityRequirement{{new OpenApiSecurityScheme{Reference = new OpenApiReference{Type = ReferenceType.SecurityScheme,Id = "Bearer"}},new string[] {}}});
});
解析：
-
AddSecurityDefinition配置了 Swagger 如何接受 API 的认证信息，这里使用了Bearer方案，即在请求头中传递 JWT Token。 -
AddSecurityRequirement设置了所有 API 请求都需要提供认证信息。
在 Swagger UI 中，用户可以通过输入 JWT Token 来进行身份认证和测试。
4. Basic 认证配置
除了 JWT 认证，Basic 认证也是一种常见的认证方式。在某些项目中，你可能需要使用 Basic 认证来保护 API。
配置代码：
builder.Services.AddSwaggerGen(c =>
{c.AddSecurityDefinition("Basic", new OpenApiSecurityScheme{In = ParameterLocation.Header,Name = "Authorization",Type = SecuritySchemeType.Http,Scheme = "basic",Description = "Basic Authentication"});c.AddSecurityRequirement(new OpenApiSecurityRequirement{{new OpenApiSecurityScheme{Reference = new OpenApiReference{Type = ReferenceType.SecurityScheme,Id = "Basic"}},new string[] {}}});
});
解析：
-
通过配置
Basic认证，我们可以在 Swagger UI 中提供用户名和密码来进行 Basic 认证。 -
这种方式适用于不使用 JWT 的传统认证场景。
5. 隐藏某些 API 或控制器
在开发中，通常有一些 API 是仅供内部使用的，或者是某些需要隐藏的 API。这时我们可以通过 ApiExplorerSettings 特性将这些 API 从 Swagger 文档中排除。
配置代码：
[ApiExplorerSettings(IgnoreApi = true)]
[Route("api/[controller]")]
public class InternalController : ControllerBase
{[HttpGet]public IActionResult GetInternalData(){return Ok("这是一个内部接口，Swagger 不会显示");}
}
解析：
-
使用
ApiExplorerSettings(IgnoreApi = true)特性标记某个控制器或方法，告诉 Swagger 忽略该 API。 -
这对于那些仅供内部使用、且不想暴露的接口非常有用。
6. API 请求和响应模型文档
Swagger 自动根据控制器方法的参数和返回类型生成文档。在一些复杂的 API 中，你可能需要为请求和响应定义详细的模型，这样 Swagger 会根据模型的属性生成文档，帮助前端开发人员更好地理解如何调用 API。
配置代码：
public class RegisterRequest
{public string Username { get; set; }public string Password { get; set; }
}public class RegisterResponse
{public bool Success { get; set; }public string Message { get; set; }
}[HttpPost]
[Route("api/register")]
public IActionResult Register([FromBody] RegisterRequest request)
{var response = new RegisterResponse{Success = true,Message = "注册成功"};return Ok(response);
}
解析：
-
使用
RegisterRequest和RegisterResponse模型，Swagger 会自动生成相应的文档，描述请求体和响应体的结构。
7. 在生产环境中禁用 Swagger
为了安全起见，我们通常希望在生产环境中禁用 Swagger，防止暴露 API 文档。你可以通过环境检查来控制 Swagger 的启用与禁用。
配置代码：
if (app.Environment.IsDevelopment())
{app.UseSwagger();app.UseSwaggerUI(c =>{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系统 API v1");});
}
解析：
-
通过
app.Environment.IsDevelopment()来确保仅在开发环境中启用 Swagger。
8. 自定义 Swagger UI 外观
Swagger UI 提供了丰富的自定义选项，开发者可以根据自己的需求修改界面的标题、显示请求时长等信息。
配置代码：
app.UseSwaggerUI(c =>
{c.SwaggerEndpoint("/swagger/v1/swagger.json", "智慧OA系统 API v1");c.RoutePrefix = string.Empty;c.DocumentTitle = "智慧OA系统 API 文档";c.DisplayRequestDuration(); // 显示请求的响应时间
});
解析：
-
通过
DocumentTitle和DisplayRequestDuration等选项自定义 Swagger UI 的外观和行为。
9. 总结
在 .NET Core 中集成 Swagger
可以显著提高 API 文档的生成效率和使用体验。通过本文所述的基本配置和常见的高级配置，您可以根据项目需求对 Swagger 进行定制，从而更好地管理 API 文档和接口测试。
无论是多版本支持、认证配置、隐藏 API 还是自定义 Swagger UI，灵活使用这些功能可以帮助团队提高开发效率，减少沟通成本，并确保 API 的正确使用。
希望这篇文章能够帮助您在项目中更好地整合和配置 Swagger，提高开发体验与文档质量。