.NET 9内置OpenAPI文档生成 — 说再见SwaggerUI！👋

改为：

最终修改为：

Swagger UI（https://swagger.io/）是一个开源的工具，可以自动生成一个具有交互功能的基于网页的WebAPI文档界面。它支持OpenAPI标准规范。从2020年到2024年，它在ASP.NET Core开发人员中非常流行，因为它默认内置在ASP.NET Core模板中。我们喜欢这个工具，因为它是我们用来测试WebAPI调用的第一个工具。现在它还提供付费和免费服务。

从.NET 5到.NET 8期间，Swagger默认集成在.NET Web模板里。

开放API是一种定义REST API的标准规范。官方网站是 https://www.openapis.org/。微软现在也在使用开放API，官方文档在这里 👉 https://aka.ms/aspnet/openapi。

#

#

#

#

Swagger UI 不再集成于 .NET 9，因为 Microsoft 希望有更好的解决方案，拥有更好的控制和增强的安全保障。如下面的截图所示，如 Microsoft 所声明的，它已被移除。

在 2024 年 3 月，ASP.NET Core 团队成员宣布他们将从网页模板中删除 Swashbuckle.AspNetCore 依赖项，该更改将在 .NET 9 发布后应用。

_> 这个决定是因为该项目缺乏活跃维护以及没有.NET 8的官方发行版本。

微软团队创建了一个新的包 Microsoft.AspNetCore.OpenApi。它提供了内置的 OpenAPI 文档生成功能，就像 Swagger 一样。因此，微软不再需要依赖外部工具。因为每次 .NET 发布时，都需要让外部工具库的所有者升级到新版本，以保持一致性。有时，这些库的所有者无法根据最近的 .NET 更改来更新他们的代码库。因此，微软支持这些第三方库越来越困难。因此，减少这种第三方依赖有助于微软加快其发布周期。

我看了关于这个话题的 Reddit、GitHub 讨论和 YouTube 评论。从中，社区成员对 Swashbuckle 不活跃的状况表示了担忧，并开始讨论替代方案，比如为该项目贡献代码或分叉。微软团队也联系了 Swashbuckle 和 NSwag 的所有者们，探讨潜在的合作机会，并确保开发人员能够顺利过渡。

以下 GitHub 讨论中可以查看有关此决定的详细信息

GitHub上的aspnetcore问题54599

杰里米（Jeremy） — 微软的产品经理杰里米，在这篇帖子中解释了为什么他们做出了这个决定。

这种变化是由于 Swagger 库的维护不足，尽管它最近也经历了一些更新。这旨在减少对外部工具的依赖性，并为 ASP.NET Core Web API 生成 OpenAPI 文档提供一个简洁且即插即用的体验。

1.) 本机支持和减少依赖
新的 Microsoft.AspNetCore.OpenApi 包提供了对 OpenAPI 的原生支持。它减少了对 Swashbuckle 或 NSwag 这些外部工具在基本文档上的依赖。原生实现通过利用源生成器来减少运行时的开销。

2. 简化的配置
无需额外设置或第三方集成。只需定义控制器和端点，，ASP.NET Core 会自动为你生成 OpenAPI 规范。

3.) 最小API的无缝集成
在.NET 6中引入的最小API提供了内置优化支持，它会自动为路由、请求参数和响应添加元数据。

4.) 与现有工具的兼容性
您仍然可以将OpenAPI的输出与Swagger或NSwag工具配合使用，因此使用OpenAPI并不限制您的选择。

当你创建一个新的ASP.NET Core项目时，你可以看到下面的勾选框，用来添加OpenAPI功能。

我新建了一个.NET 9的Web项目，看到OpenAPI已经加进来了。

将你的项目更新到 .NET 9，然后添加所需的 此链接 NuGet 包。

    dotnet 安装包 Microsoft.AspNetCore.OpenApi

在 Program.cs 文件中添加以下服务与中间件：

    var builder = WebApplication.CreateBuilder();  
    builder.Services.AddOpenApi(); // 添加OpenApi支持  
    var app = builder.Build();  
    app.MapOpenApi(); // 映射OpenApi  
    app.MapGet("/", () => "试试"); // 映射根路径到一个简单的测试字符串  
    app.Run();

您的 OpenAPI 文档链接是 https://localhost:7077/openapi/v1.json

把端口改成你的活跃端口。看起来像这样：

Scalar 是一个开源的 RESTAPI 文档平台，主要用于生成文档。它还提供了一个与 RESTful API 交互的界面。生成交互式且易于用户使用的 API 文档。支持 OpenAPI 和 Swagger 规范，确保文档的一致性和兼容性。它是一个开源项目，在 GitHub 上获得了 7000 颗星。

查看仓库 👉 https://github.com/scalar/scalar

关于在 .NET 9 中替换 Swagger 的内容到这里就结束了。
编码愉快，加油 👍

🧑🏽‍💻 我是 阿尔佩尔·埃比科卢，ABP 框架的核心团队成员。
关注我，了解 .NET 和软件开发的最新动态：
twitter.com/alperebicoglu
github.com/ebicoglu
linkedin.com/in/ebicoglu
medium.com/@alperonline (阿尔佩尔·埃比科卢）