使用 Swashbuckle 记录 API

  • 5 分钟

Swashbuckle 是一个 NuGet 包，可用于为 ASP.NET Web API 项目自动生成 Swagger 文档。 Swagger 是一种工具，可帮助开发人员设计、生成、记录和使用 RESTful API。 借助 Swashbuckle，可使用描述 API 终结点、参数和响应的属性来批注代码，将 Swagger 文档轻松添加到 Web API 项目。 Swashbuckle 随后会使用此信息生成 Swagger JSON 文件，该文件可用于生成交互式 API 文档、客户端 SDK 等。

Swashbuckle 有三个主要组件：

  • Swashbuckle.AspNetCore.Swagger：一个 Swagger 对象模型和中间件，用于将 SwaggerDocument 对象作为 JSON 终结点公开。

  • Swashbuckle.AspNetCore.SwaggerGen：一个 Swagger 生成器，可直接从路由、控制器和模型构建 SwaggerDocument 对象。 它通常与 Swagger 终结点中间件结合使用，以自动显示 Swagger JSON。

  • Swashbuckle.AspNetCore.SwaggerUI：Swagger UI 工具的嵌入式版本。 它解释了 Swagger JSON，以便为描述 Web API 功能构建丰富、可自定义的体验。 它包括针对公共方法的内置测试工具。

以下 dotnet add 命令可安装 Swashbuckle NuGet 包：

dotnet add <name>.csproj package Swashbuckle.AspNetCore -v 6.5.0

添加并配置 Swagger 中间件

将 Swagger 生成器添加到 Program.cs 中的服务集合。

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

注意

最小 API 只需要上一示例中显示的对 AddEndpointsApiExplorer 的调用。

此外，在 Program.cs 中，启用中间件为生成的 JSON 文档和 Swagger UI 提供服务：

app.UseSwagger();
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI();
}

Swagger UI 的默认终结点为 http:<hostname>:<port>/swagger。

注意

SwaggerUI 在开发环境中非常有用。 它可以在生产环境中启用，但在启用前应考虑特定应用程序的安全要求。

自定义和扩展 Swagger 文档

Swagger 提供了用于记录对象模型和自定义 UI 的选项。 传递给 AddSwaggerGen 方法的配置操作可以通过 OpenApiInfo 类包含额外信息。

以下代码示例演示如何添加要在 API 文档中显示的信息。

// Add using statement for the OpenApiInfo class
using Microsoft.OpenApi.Models;

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "Fruit API",
        Description = "API for managing a list of fruit their stock status.",
        TermsOfService = new Uri("https://example.com/terms")
    });
});

Swagger UI 会显示版本和添加的信息：

显示添加至 API 的其他描述性信息的屏幕截图。

可以使用 .WithTags 选项对 API 中的操作进行分组。 还可以添加描述性文本，使用 .WithSummary 选项描述操作。 以下示例代码演示如何用 .WithTags 将 POST 操作同时分组到发布组和水果组中。 它还将 .WithSummary 选项中指定的摘要添加到操作。

app.MapPost("/fruits", async (Fruit fruit, FruitDb db) =>
{
    db.Fruits.Add(fruit);
    await db.SaveChangesAsync();

    return Results.Created($"/{fruit.Id}", fruit);
})
    .Produces<Fruit>(201)
    .WithTags("post", "fruits")
    .WithSummary("Create a new fruit");

Swagger UI 会显示指定的分组和摘要说明。

Swagger UI 的屏幕截图，其中显示了两个组中的发布操作，包含摘要说明。