学习 C#

在Linux上为.NET Aspire添加Swagger UI

Tim Corey

7m 24s

通过在浏览器中手动键入 URL 来测试 API 端点以进行快速合理性检查是可行的，但当您有多个带有不同 HTTP 动词和请求主体的路由时，这种方法就不太适用了。 Swagger UI 为您提供了一个交互式基于浏览器的面板，您可以在其中调用每个端点，检查响应，并实验参数，而无需编写单独的客户端或记住 curl 标志。

在他的视频《在 Linux 上向 .NET Aspire 添加 Swagger UI》中，Tim Corey 从前一集的 Tiny Ticket 项目开始，在现有的 OpenAPI 配置上添加了 Swagger UI。这个过程需要三行代码和一个 NuGet 包。然后，他演示了通过 Swagger 接口调用票务端点，包括在机器重启后未启动的数据库连接的故障排除。如果您正在 Linux 系列上的 C# 中构建 API，或想快速参考如何在 .NET 项目中连接 Swagger，本文涵盖了每一个步骤。

安装 Swashbuckle NuGet 包

[0:38 - 1:35] Tim 在 VS Code 中打开 Tiny Ticket 项目并导航到 API 服务的 Program.cs。 API 已经有一个来自上一集的 GET /api/tickets 端点，但调用它需要手动构造 URL。要添加一个合适的测试接口，第一步是安装 Swagger UI 包。

右键点击 API 项目，选择"添加 NuGet 包"，然后搜索 Swashbuckle.AspNetCore.SwaggerUI。 Tim 安装了录制时的最新版本（10.1.7）。安装后，包引用出现在项目文件中。不需要其他依赖，因为项目已经通过默认的 Aspire 服务配置包含了对 OpenAPI 的支持。

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

// Verify the package was added to the .csproj
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="10.1.7" />

在 Program.cs 中配置 Swagger UI

[1:35 - 3:12] 包安装完成后，配置会进入 Program.cs 的开发专用块中。项目已经注册了 app.MapOpenApi()，它在运行时生成 OpenAPI 规范文件。Swagger UI 只需知道该文件的位置以及如何标记端点组。

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();

    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Ticket App API v1");
    });
}

SwaggerEndpoint 调用指向 .NET 自动生成的 OpenAPI 规范。第二个参数是 Swagger UI 下拉菜单中显示的名称。 Tim 强调这三行是整个 Swagger 设置。您可以添加更多配置来自定义 UI、分组端点或添加身份验证头，但对于开发测试工具，默认设置就足够了。

有一点值得注意：自 .NET 9 以来，新的 API 项目默认不再包括 Swagger。微软通过将 OpenAPI 作为标准来分离问题，并让开发者选择他们更喜欢的 UI 层。 Swagger、Scalar 和其他工具都使用相同的 OpenAPI 规范文件，因此您无需被锁定在任何特定的查看器中。

运行并验证 Swagger 接口

[3:12 - 6:07] 保存后，Tim 通过运行和调试面板启动项目。一旦 Aspire 仪表板加载并显示 API 服务正在运行，他导航到 API 的 URL 并在路径末尾附加 /swagger。

Swagger UI 加载，并显示"Ticket App API v1"标签和可用的端点。根端点 (/) 返回一个简单的健康消息，/api/tickets 则返回数据库中的票据数据。

Tim 点击根端点上的"Try it out"并执行它。响应返回 200 状态和确认消息。然后他移动到 /api/tickets 端点并执行，这是故障排除开始的地方。

第一次尝试由于连接错误失败："在建立与 SQL 服务器的连接时发生与网络相关或特定于实例的错误。" 数据库容器在机器重启后没有启动。 Tim 打开 Portainer，找到 SQL Server Docker 容器，并启动它。容器初始化完成后，他返回 Swagger 并再次执行请求。这一次，响应返回 200，并从数据库中存储了三张测试票。

该序列实际提醒集成测试会暴露单元测试和模拟数据无法捕获的问题。数据库容器未设置为在启动时自动启动，这意味着在重启后第一个 API 调用将失败，除非您先验证容器状态。

接下来是什么：CRUD 端点

[6:07 - 7:20] Tim 预览了系列中的即将到来的剧集。 Tiny Ticket API 目前只有 GET /api/tickets 端点，它映射到 spTickets_GetAll 存储过程。数据库中的剩余存储过程（按 ID 获取、插入、更新、删除）每个都需要一个对应的 API 端点以及正确的 HTTP 动词：GET 用于检索，POST 用于创建，PUT 用于更新，DELETE 用于移除。

他注意到每个端点都遵循相同的模式，并且实现起来很简单，但即将到来的视频将逐一介绍它们，以便每个部分都易于单独参考。选择将系列分成小而集中的片段意味着您可以直接跳到所需的端点类型，而无需在较长的视频中翻来翻去。

结论

[7:20 - 7:24] 在 Linux 上为 .NET Aspire 项目添加 Swagger UI 需要一个 NuGet 包和在 Program.cs 中的三行配置。默认的 Aspire 服务设置已生成 OpenAPI 规范文件，因此 Swagger 只需指向该文件并设置显示名称。从这里，API 中的每个端点都可以通过浏览器测试，而无需构建单独的客户端。

Tim 在重启后遇到的数据库连接问题强调了一个实际点：当您的开发堆栈包含容器时，在测试 API 端点之前验证它们是否正在运行。 Swagger 为您提供了快速验证反馈回路。

**系列导航：**本文是 C# on Linux 系列的一部分，构建 Tiny Ticket 应用程序。上一个：在 Linux 上设置 .NET Aspire。下一步：添加按 ID 获取端点。

示例提示：如果您更喜欢不同的 OpenAPI 查看器而不是 Swagger，请安装如 Scalar 或 RapiDoc 之类的包，并指向相同的 /openapi/v1.json 端点。规范文件与 UI 无关，因此您可以在不更改 API 配置的情况下切换查看器。

观看完整视频，并在他的 YouTube频道上获取更多关于 C# on Linux 系列中构建 API 的见解。