.NET 9 彻底改变了 API 文档：从 Swashbuckle(Swagger) 到 Scalar

 示例代码下载：https://download.csdn.net/download/hefeng_aspnet/90404652 

摘要

        API 文档是现代软件开发的支柱。随着 .NET 9 从 Swashbuckle 转向 Microsoft.AspNetCore.OpenApi，开发人员需要新的策略来保持高效。本文探讨了这些变化，并介绍了 API 文档的变革者 Scalar。
 

       本文深入探讨了 Swagger 在 ASP.NET 生态系统中的演变和集成，重点关注 .NET 9 中的新发展。它追溯了 Swagger 从其作为开源项目的起源到其被广泛采用作为 .NET 领域中 API 文档、测试和客户端代码生成的事实上的工具的历程。随着 .NET Core 的成熟，Swashbuckle 等 Swagger 工具简化了向 ASP.NET 应用程序添加交互式文档和 OpenAPI 支持的过程。但是，随着 .NET 9 的发布，Swashbuckle.AspNetCore 已被弃用，取而代之的是 Microsoft.AspNetCore.OpenApi 库。本文提供了有关如何将 Swagger 整合到 .NET 9 Web API 中的实用指导，并强调了向更现代、更高效的工具的转变。它还介绍了 Scalar .NET，这是一个创新平台，它通过时尚的用户界面和一流的 OpenAPI 支持增强了 Swagger。本文提供了分步说明和代码示例，为希望在 .NET 9 中实现 API 文档策略现代化的开发人员提供了全面的资源。

Swagger 的故事
        ASP.NET 中 Swagger 的故事与 API 驱动开发的兴起以及对更好的方法来记录、测试和与 API 交互的需求交织在一起。以下是 Swagger 如何成为 ASP.NET 开发人员的关键工具的细分：

API 的兴起
        随着 RESTful API 成为现代应用程序开发的核心，开发人员面临着创建清晰一致的文档的挑战。传统的文档方法容易出错且难以维护，尤其是对于大型 API。Swagger
于 2011 年作为 Tony Tam 的一个开源项目出现。它旨在标准化 API 的描述方式，使工具能够自动生成交互式文档、客户端 SDK 和服务器存根。

.NET 中的早期采用
        ASP.NET 开发人员很快就看到了 Swagger 的潜力。然而，集成最初是手动的，需要开发人员手动编写 Swagger 规范文件（以 JSON 或 YAML 格式）。这个过程很繁琐，阻碍了采用。

Swashbuckle 让 Swagger 变得天衣无缝
        Swashbuckle 由 Richard Morris 创建，是 ASP.NET 开发人员的一大变革。它提供了一种将 Swagger 集成到 ASP.NET 项目中的简便方法，可自动从 Web API 控制器和路由生成 Swagger JSON。

Swashbuckle 添加了以下功能：

自动文档：使用 XML 注释和数据注解直接从代码生成 API 文档。
Swagger UI 集成：将交互式 API 文档界面直接嵌入到您的应用程序中。
可定制性：允许开发人员扩展和调整 Swagger 输出。

ASP.NET Core 时代
        2016 年推出 ASP.NET Core 时，它​​就以模块化和灵活性为设计理念。这使得集成 Swagger 工具变得更加简单。Swashbuckle 适应了 ASP.NET Core，并成为 Swagger 集成的事实标准。

ASP.NET Core 时代的主要功能：

OpenAPI 规范： Swagger 于 2015 年过渡到 OpenAPI 标准，确保了更广泛的行业采用。
改进的中间件支持： ASP.NET Core 的中间件架构使得添加 Swagger 生成器和 UI 中间件变得简单。
API 版本支持： Swashbuckle 和 NSwag 等工具支持多个 API 版本，以满足不断发展的 API 的需求。

扩展 Swagger 生态系统
如今，ASP.NET 开发人员有多种使用 Swagger 的选择：

Swashbuckle：最受欢迎且功能丰富的 ASP.NET Core 解决方案。
NSwag：另一个强大的工具，支持 OpenAPI 并添加了 TypeScript 和 C# 的客户端代码生成等功能。
Azure 集成： Swagger/OpenAPI 规范通常用于将 API 与 Azure API 管理集成。

Swagger 在现代开发中的作用 ASP.NET 项目中的 Swagger（或 OpenAPI）在以下方面起着关键作用：
协作：弥合开发人员、测试人员和利益相关者之间的差距。
自动化：自动生成客户端SDK和测试工具。
开发人员体验：允许开发人员通过 Swagger UI 等工具以交互方式探索和测试 API。

Swashbuckle.AspNetCore 将在 .NET9 中删除（Swashbuckle 是否已被弃用？）
“ ASP.NET Core 团队在 .NET 5 时间范围内开始提供依赖于 Swashbuckle 的 Web API 模板。这一决定使团队能够提供对 OpenAPI 的内置支持，OpenAPI 是一种与语言无关、与平台无关的基于 Web 的 API 表示，包含发现和与基于 HTTP 的服务端点交互所需的一切。您可能更熟悉“Swagger”这个名称，它指的是一组用于处理 OpenAPI 文档的工具。OpenAPI 文档中的信息支持客户端代码生成、存根服务器代码、创建文档和动态生成基于 Web 的 UI 等场景，以交互方式测试 API。它还在人工智能应用程序中被广泛用于提供描述 API 的提示，以供生成式 AI 使用。Swashbuckle
是一个很棒的项目，我们感谢它的所有者和社区贡献者为此投入的时间和精力。该项目不再由其社区所有者积极维护。问题尚未得到解决，并且没有针对 .NET 8 的官方版本。ASP.NET Core 团队将在 .NET 9 版本中提供解决方案。计划是从 Web API 模板中删除对 Swashbuckle.AspnetCore 的依赖，并扩展 Microsoft.AspNetCore.OpenApi 引入的功能以提供 OpenAPI 文档生成。 ”
有关 Swashbuckle.AspNetCore 弃用的更多详细信息，请参阅此 GitHub 问题。

Swagger 的未来
        随着 Microsoft 不断改进 ASP.NET Core 和 OpenAPI 成为行业标准，Swagger 有望继续成为生态系统不可或缺的一部分。ASP.NET Core 6+ 中的极简 API 等功能使集成 Swagger 以实现轻量级和高性能 API 变得更加容易。尽管已从 Webapi 示例中删除了 Swagger，但它仍在更新并可供使用。

如何将 Swashbuckle（实际操作）添加到 .Net9 webapi
        我将告诉您如何使用 SwashBuckle 将 Swagger 添加到您的 .Net Web API 项目中
开始之前，请确保您的系统上正确安装了 .Net 版本 9 SDK

首先使用此命令创建一个新的 webapi 项目
Dotnet new webapi -n OpenApi-Swagger-Scalar

然后在 VsCode 中打开你的项目，
接下来右键单击项目资源管理器中的空白区域，然后单击在集成终端
中打开， 接下来运行此命令
dotnet add package Swashbuckle.AspNetCore

现在是时候在Program.cs中配置 Swagger 了

（您会在program.cs中看到有关 OpenApi 的一些信息

builder.Services.AddOpenApi();
app.MapOpenApi();

（我们将在本主题的后面讨论该主题）

添加以下行：
builder.Services.AddOpenApi();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

在 app.MapOpenApi() 下面添加以下几行
 app.UseSwagger(); // Enable the Swagger JSON endpoint
 app.UseSwaggerUI(); // Enable the Swagger UI
 
运行你的项目并打开 uri：
http://localhost:{your_port}/swagger/index.html

或者直接导航到/swagger
例如
http://localhost:5000/swagger

恭喜！您再次在 .Net9 中拥有了 SwashBuckle Swagger！

OpenApi 的故事
        OpenAPI，以前称为 Swagger，是描述 REST API 的规范。它允许开发人员以人机可读的格式定义其 API 的结构，包括端点、操作、参数和身份验证方法。OpenAPI
规范 (OAS) 最初由 Tony Tam 于 2010 年作为 Swagger 项目的一部分开发。目标是创建一种描述 API 的标准方法，使开发人员更容易设计、构建、记录和使用 API。2015 年，Swagger 项目被捐赠给行业领导者联盟 OpenAPI Initiative，该规范更名为 OpenAPI。Swagger
工具（例如 Swagger Editor、Swagger UI 和 Swagger Codegen）都是围绕 OpenAPI 规范构建的，旨在帮助开发人员更高效地使用 API。这些工具允许开发人员编写 OpenAPI 定义、生成交互式 API 文档以及使用各种编程语言创建服务器存根和客户端库。
API 通过 OpenAPI 描述自身结构的能力彻底改变了 API 开发，实现了跨不同工具和平台的更好协作、自动化和集成。

让我们告诉你第一个秘密😊
在上一节的测试项目中，你的 Program.cs 中有这两行
builder.Services.AddOpenApi();
app.MapOpenApi();

在调试您的测试项目时，让我们导航到此链接
http://localhost:{your_port}/openapi/v1.json
例如
http://localhost:5000/openapi/v1.json
您可以看到有关所有 api 的所有文档。

OpenAPI 与 Swagger
        Swagger 项目于 2015 年捐赠给 OpenAPI Initiative，此后被称为 OpenAPI。这两个名称可以互换使用。但是，“OpenAPI”指的是规范。“Swagger”是指 SmartBear 的开源和商业产品系列，它们与 OpenAPI 规范配合使用。后续开源产品（例如 OpenAPIGenerator）也属于 Swagger 系列，尽管不是由 SmartBear 发布的。

简而言之：

OpenAPI 是一种规范。
Swagger 是使用 OpenAPI 规范的工具。

例如，OpenAPIGenerator 和 SwaggerUI。您可以在此处信息：microsoft.com

将 SwaggerUI 与 OpenApi json 的功能结合使用
因此，当我们已经有如下所示的 OpenApi 时，
app.MapOpenApi();

还有另一种选择，Swagger 可以从 OpenApi 文档中受益，以生成它的 UI，而不是swagger json 端点。
因此，我们可以删除此行，
app.UseSwagger();

而不是这一行，
app.UseSwaggerUI();

您可以像这样使用
 app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "Your Custom Title");
    });

Scalar，改变游戏规则！
        Scalar .NET 是一个开源 API 平台，它提供现代 REST API 客户端和精美的 API 参考，并提供一流的 OpenAPI/Swagger 支持。Scalar.AspNetCore 包可轻松将 Scalar API 参考集成到您的 .NET 应用程序中。您可以在此处信息。

如何将 Swashbuckle（在实践中）添加到 .Net9 webapi

安装包：使用以下命令将 Scalar.AspNetCore 包添加到您的 .NET 示例项目中：
dotnet add package Scalar.AspNetCore

将此行添加到Program.cs上方作为命名空间
using Scalar.AspNetCore;

确保你的program.cs中有这些行
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
app.MapOpenApi();

现在将此行添加到Program.cs
app.MapScalarApiReference();

当调试你的测试项目时，让我们导航到这个链接
http://localhost:{your_port}/scalar/v1
例如
http://localhost:5000/scalar/v1
你可以看到一个新的现代和非常酷的 UI 来测试你的 api：

是时候告诉你第二个秘密了😊
而不是这句话
app.MapScalarApiReference();

让我们使用类似这样的东西
app.MapScalarApiReference(options =>
{
    options
    .WithTitle("Your Custom Title")
    .WithTheme(ScalarTheme.Mars)
    .WithDefaultHttpClient(ScalarTarget.CSharp, ScalarClient.HttpClient);
});
轰！！！

        · 现在你有了自定义标题
        · 你有一个很棒的主题
        · 您默认使用 C# 代码

所有解决方案现在您拥有所有这些链接，可以使用Program.cs
中存在的这些代码行进行测试
builder.Services.AddOpenApi();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
app.MapOpenApi();
app.UseSwagger(); // Enable the Swagger JSON endpoint
app.UseSwaggerUI(); // Enable the Swagger UI
app.MapScalarApiReference();

基于 Json 的 api 文档
http://localhost:5000/openapi/v1.json
http://localhost:5247/swagger/v1/swagger.json

基于 UI 的
http://localhost:5000/swagger/index.html
http://localhost:5000/scalar/v1

总结
        本文探讨了 Swagger 在 ASP.NET 生态系统中的演变及其与 .NET 9 的集成，重点介绍了 OpenAPI 和 Scalar 平台。

        它首先详细介绍了 Swagger 的历史、它作为标准化 API 文档的开源工具的出现以及 ASP.NET 开发人员的早期采用。本文重点介绍了 Swashbuckle 等工具如何使 Swagger 更易于与 ASP.NET Core 集成，从而自动化 API 文档并增强开发人员体验。随着 .NET Core 的发展，Swagger 成为 API 文档、测试和客户端代码生成的关键工具。

        随着 .NET 9 的发布，Swashbuckle.AspNetCore 已被弃用，ASP.NET Core 团队计划扩展 Microsoft.AspNetCore.OpenApi 库。本文提供了将 Swagger（通过 Swashbuckle）添加到 .NET 9 Web API 项目的实用步骤，并讨论了从 Web API 模板中删除 Swagger，并提出了 API 文档的替代方案。

        本文还介绍了 Scalar .NET，这是一个现代平台，它通过漂亮的 UI 和 OpenAPI 支持增强了 Swagger。它展示了如何将 Scalar 集成到 .NET 项目中，从而提供更精致、更可定制的 API 参考解决方案。

        总之，本文介绍了 Swagger 在 .NET 生态系统中的历史、演变和未来，以及在 .NET 9 中使用 Swagger 和 Scalar 进行高效 API 文档编写的实用指南。借助提供的工具和见解，您现在可以在 .NET 9 中对 API 文档进行现代化改造。无论是利用 Scalar 还是坚持使用 OpenAPI，关键在于适应并保持领先于不断发展的标准。

源代码可在此处下载：https://download.csdn.net/download/hefeng_aspnet/90404652

如果您喜欢此文章，请收藏、点赞、评论，谢谢，祝您快乐每一天。