ASP.NET Core 6 中的 AddEndpointsApiExplorer 是什么

Question

我正在將 ASP.NET Core API 項目從 v5 升級到 v6。

v5中的服務配置：

services.AddSwaggerGen();

v6中的服務配置：

builder.Services.AddEndpointsApiExplorer();    // what is this?
builder.Services.AddSwaggerGen();

什么是AddEndpointsApiExplorer ？ 無論我是否添加，一切都按預期工作。

我使用“ASP.NET API 版本控制”庫。 他們有關系嗎？ 如果是這樣，我必須同時使用兩者，只使用圖書館，還是現在不需要圖書館？

Answer 1

AddEndpointsApiExplorer適用於最小 API ，而AddApiExplorer至少需要 MVC 核心。 對於 API 個項目， AddControllers代表您調用AddApiExplorer 。

但為什么一切仍然適用於AddEndpointsApiExplorer ？

隨着Endpoint Routing的引入，路由系統中的一切都歸結為Endpoint 。 ASP.NET Core 使用Application Model ，即ApplicationModel 、 ControllerModel和ActionModel來創建Endpoint實例並將它們注冊到路由系統。 但是，最小 API使用構建器直接創建和注冊各個Endpoint實例。

默認的 API Explorer 實現提供了一個IApiDescriptionProvider ，它從Application Model構建ApiDescription實例。 最小 API沒有應用程序 Model ，因此沒有任何東西可以從中構建ApiDescription實例。 API Explorer 提供了這些描述，OpenAPI 生成器等工具通常使用這些描述。 沒有任何描述，就沒有對Minimal APIs和 OpenAPI 的支持； 那會很糟糕（或者，至少，肯定不會被開發人員接受）。 為了解決這個問題，ASP.NET Core 團隊創建了第二個IApiDescriptionProvider ，它只考慮Endpoint 。

如果一切都是Endpoint ，為什么不合並實現？

這個答案有兩個部分。 首先，改變原來的IApiDescriptionProvider實現會引入一個公共的、破壞性的變化。 至少，需要新的構造函數 arguments。 由於這是一個主要的版本沖突，這種方法並沒有被排除在外，但事實證明它是無關緊要的。 更大的問題是原始的IApiDescriptionProvider實現和AddApiExplorer存在於並依賴於 MVC Core。 最小 API只需要路由抽象。 如果不添加不必要的耦合，就無法將兩者合並。 為了解決這個問題，添加了AddEndpointsApiExplorer ，它添加了一個實現，該實現只需要一個IApiDescriptionProvider實現，該實現基於來自路由系統的基本Endpoint定義。

如果AddEndpointsApiExplorer存在並且我調用它，我還需要AddApiExplorer嗎？ 或許。 最小 API Endpoint實例上公開和可用的元數據比應用程序 Model輕得多； 畢竟，它們是最小的。 在幕后， IApiDescriptionGroupCollectionProvider實現采用一系列IApiDescriptionProvider實例。 如果AddEndpointsApiExplorer和AddApiExplorer ，則兩個提供程序都將執行。 如果僅AddEndpointsApiExplorer ，它將與常規的“ol 控制器”一起工作，但描述的信息保真度可能低於您所習慣的。 如果您只編寫Minimal APIs ，那么如果您想要AddEndpointsApiExplorer Explorer 支持，則需要 AddEndpointsApiExplorer。

兩種方法之間的保真度在 .NET 7.0 中得到了更大的提高。 在未來的某個版本中，我們可能會看到這些方法合並為一個。

Answer 2

TLDR； .AddEndpointsApiExplorer()的創建是為了支持Minimal Api 的.

通過谷歌搜索文檔顯示了許多頁面，其中包括對.AddEndpointsApiExplorer()的調用。 但是沒有提到為什么需要它，或者在從 v5 項目遷移時是否需要它。 肯定缺少文檔。

從源碼逆推& git怪，找到了相關工程。 所以答案似乎與對Minimal Api 的支持有關。

我相信一些新服務的創建是為了從這些新的最小 api 中提取返回類型信息，這種方式在不使用 MVC 的情況下使用端點路由時可能會以更通用的方式應用。

如果您使用的是 MVC，可能會通過.AddControllers()為您調用.AddApiExplorer() 。 提供swagger所依賴的服務，用於描述controller的動作。 如果這就是您所需要的，那么似乎不需要這個新的 api 電話。

雖然使用swagger和最少 api 的文檔包括對.AddEndpointsApiExplorer()的調用。 即使這樣也不能准確解釋為什么需要它。

為什么.AddEndpointsApiExplorer()存在？ 為什么新功能被排除在.AddApiExplorer()之外？ 為什么這個方法重命名被排除在 v6 的其他文檔之外？

也許我們應該在https://github.com/do.net/as.netcore/或https://github.com/do.net/AspNetCore.Docs/上創建一個問題來要求澄清，這樣其他人就不會不得不問這些問題。

Answer 3

長話短說

如果您使用 v6 的“最小 API”，則僅使用AddEndpointsApiExplorer ，如下所示：

app.MapGet("/", () => "Hello World!");