在 .NET 9 API 中替代 Swagger 的 4 个选项

建立标准 API 项目

Tim 首先在 Visual Studio 中创建了一个最小的 API 项目，选择了标准的 ASP.NET Core Web API 模板。

他强调要勾选添加 OpenAPI 支持的复选框，以确保您的项目通过 JSON 文件端点生成必要的 OpenAPI 文档。

项目运行后，Tim 会导航到默认的 OpenAPI 文档 URL（如 /swagger/v1/swagger.json），查看原始 OpenAPI 规范。 该文件包含有关 API 端点的结构化元数据，包括支持的 GET、POST 和 DELETE 等动词。

虽然功能强大，但 Tim 指出，查看原始 OpenAPI 文档对用户并不友好。 为了提供更好的网络文档界面，他接着演示了四种外部工具，以增强开发人员和消费者的体验。

选项 1：Swagger UI - 熟悉的体验

Swagger UI 仍然是一个非常受欢迎的工具，尽管默认情况下已不再包含它。 Tim 演示了如何使用所需的 NuGet 包 dotnet 将其还原：Swashbuckle.AspNetCore.SwaggerUI.

在新项目中设置 Swagger UI 后，在 9:43 处，他使用简化语法配置中间件，并将启动 URL 设为 /swagger。 该用户界面提供了一个用户友好的 API 文档界面，开发人员可以在此查看端点、了解请求参数并在浏览器中进行测试。

虽然 Swagger UI 现在是一个外部工具，但它仍然支持 OpenAPI 规范，是满足开发过程中基本文档需求的最佳选择之一。

选项 2：ReDoc - 简洁、只读的 API 文档

Tim 的第二个工具是 ReDoc，它可以将 OpenAPI 文档转换为精练的只读 HTML 网站。添加 OpenAPI 包 Swashbuckle.AspNetCore.ReDoc 后，他将文档映射到 /api/docs。

与 Swagger UI 不同，ReDoc 不允许进行端点测试。 不过，作为适合外部用户和客户使用的基于网络的文档界面，它也会大放异彩。 如果您只专注于定义 REST API 和显示结构化文档，ReDoc 将是您的最佳选择。

值得注意的是，ReDoc 会根据所提供的 OpenAPI 规范自动生成内容，包括预期的响应、参数和数据类型。这与优先优化内置文档支持而非交互性的项目非常吻合。

选项 3: NSwag - 文档 + 代码生成

接下来，Tim 将深入介绍 NSwag，这是一款灵活且功能丰富的工具，它不仅可以记录 API，还可以用 C#、TypeScript 等各种语言为客户端生成代码。 安装 NSwag.AspNetCore NuGet 包后，他设置了类似 Swagger 的接口，将其映射到相同的 JSON 端点。

Tim 解释说，NSwag 同时支持 Swagger 规范和 OpenAPI 标准，允许开发人员选择自己喜欢的格式。 虽然用户界面看起来与 Swagger 相似，但 NSwag 的外部工具库和高级功能（如自动创建客户端）却让它大放异彩。

他指出，NSwag 生成代码的能力有助于减少集成 API 时的人工工作量，尤其是在涉及多个服务或外部工具的项目中。 对于构建强大的客户端-服务器通信的团队来说，这是一个强大的解决方案。

选项 4：Scaler--Tim 在 API 测试中的最爱

Tim 介绍说，Scaler UI 是所有选项中他个人最喜欢的一个，并将其描述为 Postman 和浏览器中文档的混合体。 添加 Scaler.AspNetCore 软件包后，只需一行代码（app.MapScalerApiReference()）即可启用接口。

Scaler 支持全面的交互性，包括执行带有查询参数、标头和 cookie 的请求。 它的与众不同之处在于实时反馈--它会立即返回响应时间、标头和结果有效载荷。

Scaler 的一个突出特点是能够生成不同语言（通过 HttpClient 和 RestSharp 生成 PHP、Node、Python、C#）的 curl 命令和客户端代码片段。 Tim 发现这对于在开发过程中快速复制和粘贴 API 调用特别有用。

Scaler 还可以在明暗模式之间切换，是一个用户友好型 API 文档平台，还有进一步改进的空间。 作为一个开源 API 平台，Scaler 通过积极的维护和浓厚的社区兴趣不断发展。

最后的想法：选项带来灵活性

在视频的最后几分钟，Tim 强调说，将 Swagger UI 从 .NET 网页模板中移除似乎是一种退步，但这实际上是一个拥抱现代、更有针对性的解决方案的机会。 这一变化与微软的快速发布周期相吻合，其功能变得更加模块化和集中化。

OpenAPI 支持现在更像是一种一等公民支持，而不是僵化的本地实现。 您可以根据项目的需要自由搭配工具--无论是使用 Scaler 进行交互式测试、使用 NSwag 生成客户端代码，还是使用 ReDoc 进行简洁输出。

Tim 鼓励开发人员探索这些工具，看看哪一个适合他们的工作流程，甚至可以针对不同的环境使用多个用户界面（例如，一个用于开发，另一个用于公共文档）。 事实上，所有这些选项都支持 OpenAPI 和 Swagger 规范，这意味着您不会被锁定在单一供应商或工作流程中。

结论

由于在 .NET 9 中取消了 Swagger UI 的默认设置，开发人员现在可以自由选择最适合其 OpenAPI 文档需求的工具。 无论您是记录 HTTP API、为外部工具提供服务，还是支持内部开发，总有一款解决方案符合您的目标。

有了 Swagger UI、ReDoc、NSwag 和 Scaler 等工具，编写和测试 API 的可定制性和开发人员友好性都得到了前所未有的提高。 正如 Tim Corey 在他的视频中向我们展示的那样，只需要几个软件包、几行代码，以及探索最适合您的应用程序和团队的工具的愿望。