什么是 Swagger UI？
Swagger UI 是一款开源工具，它能为 Web API 自动生成一个交互式的、基于网页的文档界面。它支持 OpenAPI 标准。在 2020 年至 2024 年间，它在 ASP.NET Core 开发人员中是一款非常受欢迎的工具，因为它是 ASP.NET Core 默认模板自带的内置工具。我们喜欢这款工具，是因为它是首个允许我们发起 Web API 调用以进行测试的工具。如今，它既提供免费服务，也有付费服务。
此前，在.NET 5 到.NET 8 的.NET 网页模板中，Swagger 是默认包含在内的。
什么是 OpenAPI？
OpenAPI 是一种用于定义 REST API 的标准规范。其官方网站是 https://www.openapis.org/ 。微软现在也在使用 OpenAPI，官方文档在此👉 https://aka.ms/aspnet/openapi 。
用 OpenAPI 替换 Swagger UI
Swagger UI 在.NET 9 中不再集成，因为微软希望有一个能获得一流支持、具备更好的管控能力以及更强安全性的解决方案。正如你在下面的截图中所看到的，微软宣称它已经被移除了。
为什么 Swagger 从.NET 9 中被移除？
在 2024 年 3 月，ASP.NET Core 团队宣布，他们将从.NET 9 版本的网页模板中移除对 Swashbuckle.AspNetCore 的依赖。
这一决定受到该项目缺乏积极维护以及没有针对.NET 8 的正式发布版本等因素的影响。
微软团队创建了一个新的包 Microsoft.AspNetCore.OpenApi。它能提供内置的 OpenAPI 文档生成功能，就像 Swagger 那样。所以微软不再依赖外部工具了，因为每个.NET 版本发布时都需要请求外部工具库的所有者使其与新版本适配。有时候，这些库的所有者无法根据.NET 的最新变更来更新他们的代码库，在这种情况下，微软对第三方库的支持变得愈发困难。基本上，减少第三方依赖将有助于微软加快发布周期。
我阅读了 Reddit、GitHub 上关于这个话题的讨论以及 YouTube 上的相关评论。我发现社区成员对 Swashbuckle 的不活跃状态表示担忧，并且他们正在讨论替代方案，比如为该项目做贡献或者进行项目分支（fork）。微软团队也联系了 Swashbuckle 和 NSwag 的所有者，以探索潜在的合作机会，确保开发人员能顺利过渡。
在下面这个 GitHub 问题中，你可以看到这一决定的详细情况：
github.com/dotnet/aspnetcore/issues/54599
微软的产品经理杰里米（Jeremy）在这篇帖子中回答了他们做出这一决定的原因。
“做出这一改变是因为 Swagger 库缺乏维护，尽管它最近有过一些更新。这样做的目的是减少对外部工具的依赖，并为生成 ASP.NET Core Web API 的 OpenAPI 文档提供一种简化的、开箱即用的体验。”
新的 OpenAPI 包有哪些优势？
原生支持与减少依赖 新的
Microsoft.AspNetCore.OpenApi包为 OpenAPI 提供了一流的支持。对于基本的文档需求，它减少了对像Swashbuckle或NSwag这类外部工具的依赖。其原生实现利用了源生成器来减少运行时开销。简化配置 无需额外的设置或第三方集成。只需定义控制器和端点，ASP.NET Core 就会自动生成 OpenAPI 规范。
与最小 API 良好集成 最小 API 是在.NET 6 中引入的。针对最小 API 有优化的内置支持，它会自动为路由、请求参数以及响应添加元数据。
与现有工具兼容 你仍然可以将 OpenAPI 的输出用于 Swagger 或 NSwag……所以这并不意味着在使用 OpenAPI 时你只有一种选择。
如何在.NET 9 中使用新的 OpenAPI？
当你创建一个新的 ASP.NET Core 项目时，你可以看到下面这个用于添加 OpenAPI 的复选框。
我创建了一个新的.NET 9 网络项目，我看到 OpenAPI 已经被添加进去了。
为现有项目添加 OpenAPI 支持
将你的项目升级到.NET 9，并添加所需的 NuGet 包 Microsoft.AspNetCore.OpenApi：
dotnet add package Microsoft.AspNetCore.OpenApi
在 Program.cs 中添加以下服务和中间件：
var builder = WebApplication.CreateBuilder();
builder.Services.AddOpenApi(); //<<-----
var app = builder.Build();
app.MapOpenApi(); //<<-----
app.MapGet("/", () => "Test");
app.Run();
你的 OpenAPI 文档 URL 是 https://localhost:7077/openapi/v1.json
将端口修改为你正在使用的端口。效果如下所示：
替代的第三方工具：Scalar
Scalar 是一个用于 REST API 文档的开源 API 平台。此外，它还提供了一个与 RESTful API 进行交互的界面，能生成交互式且用户友好的 API 文档，支持 OpenAPI 和 Swagger 规范。它是开源项目，在 GitHub 上有 7000 颗星。
查看项目仓库👉 https://github.com/scalar/scalar 。
如果你喜欢我的文章，请给我一个赞！谢谢
