.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，提高开发体验与文档质量。