ASP.NET Core Web API 中使用 Swashbuckle 生成 Swagger 文档教程

Swashbuckle 是一个流行的开源库，用于为 ASP.NET Core Web API 自动生成 Swagger/OpenAPI 文档。本文将详细介绍如何在 ASP.NET Core 6.x 项目中配置和使用 Swashbuckle。

基础配置

首先，我们需要在项目中添加 Swashbuckle 的基本服务配置：

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

这三行代码分别完成了：

1. 添加控制器服务
2. 添加 API 终结点探索服务
3. 添加 Swagger 生成服务

Swagger 中间件配置

在应用构建完成后，我们需要添加 Swagger 中间件：

app.UseSwagger(options =>
{
    options.SerializeAsV2 = true;
});

SerializeAsV2 选项设置为 true 表示生成的文档将使用 Swagger 2.0 格式而不是默认的 OpenAPI 3.0 格式。这在需要向后兼容旧版 Swagger 工具时很有用。

开发环境下的 UI 配置

通常我们只在开发环境下启用 Swagger UI：

if (builder.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
        options.RoutePrefix = string.Empty;
    });
}

这里有几个关键点：

• SwaggerEndpoint 指定了 Swagger JSON 文档的路径和版本名称
• RoutePrefix 设置为空字符串表示 Swagger UI 将位于应用的根路径

自定义 API 文档信息

我们可以为生成的 API 文档添加更多元信息：

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "ToDo API",
        Description = "An ASP.NET Core Web API for managing ToDo items",
        TermsOfService = new Uri("https://example.com/terms"),
        Contact = new OpenApiContact
        {
            Name = "Example Contact",
            Url = new Uri("https://example.com/contact")
        },
        License = new OpenApiLicense
        {
            Name = "Example License",
            Url = new Uri("https://example.com/license")
        }
    });
});

这些信息将显示在 Swagger UI 的顶部，帮助 API 使用者了解 API 的基本信息和联系方式。

自定义 Swagger UI 样式

Swashbuckle 允许我们自定义 Swagger UI 的样式：

if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options =>
    {
        options.InjectStylesheet("/swagger-ui/custom.css");
    });
}

要实现这一点，我们需要：

1. 创建一个 custom.css 文件
2. 确保应用启用了静态文件服务：

app.UseHttpsRedirection();
app.UseStaticFiles();
app.MapControllers();

最佳实践建议

1. 环境区分：始终将 Swagger UI 限制在开发环境，生产环境应该禁用或保护这些端点
2. 版本控制：为 API 的不同版本创建不同的 Swagger 文档
3. 安全考虑：在生产环境中考虑添加身份验证来保护 Swagger 端点
4. XML 注释：结合 XML 注释可以生成更详细的 API 文档

通过以上配置，我们可以为 ASP.NET Core Web API 项目快速搭建一个功能完善、美观实用的 API 文档系统，极大提升开发效率和 API 的可维护性。