.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(); // 显示请求的响应时间
});

解析：