.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

如果您喜歡此文章，請收藏、點贊、評論，謝謝，祝您快樂每一天。??