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. ASP.NET Core 使用应用程序模型（即和 ）ApplicationModel来创建实例并向路由系统注册它们。然而，最小 API使用构建器直接创建和注册单个实例。ControllerModelActionModelEndpointEndpoint

默认的 API Explorer 实现提供了从应用程序模型IApiDescriptionProvider构建实例的方法。最小 API没有应用程序模型，因此无法从中构建实例。API Explorer 提供了这些描述，这些描述通常由 OpenAPI 生成器等工具使用。如果没有任何描述，就不会支持Minimal APIs和OpenAPI；那会很糟糕（或者至少肯定不会被开发人员接受）。为了解决这个问题，ASP.NET Core 团队创建了第二个仅考虑.ApiDescriptionApiDescriptionIApiDescriptionProviderEndpoint

如果一切都是一个Endpoint，为什么不合并实现呢？

这个答案有两个部分。首先，改变原来的IApiDescriptionProvider实现将引入一个公开的、突破性的改变。至少需要新的构造函数参数。由于这是一个主要版本的提升，这种方法并没有被排除在外，但事实证明它是无关紧要的。更大的问题是原始IApiDescriptionProvider实现AddApiExplorer依赖于 MVC Core。最小 API仅需要路由抽象。没有办法在不增加不必要的耦合的情况下将两者合并。为了解决这个问题，AddEndpointsApiExplorer添加了一个实现，该实现只需要IApiDescriptionProvider基于Endpoint路由系统的基本定义的实现。

如果AddEndpointsApiExplorer存在并且我调用它，我还需要AddApiExplorer吗？或许。Minimal API 实例上公开和可用的元数据比应用程序模型Endpoint轻得多；毕竟，它们是最小的。在幕后，实现需要一系列实例。如果和被调用，那么两个提供者都会执行。如果仅调用，它将与常规“ol 控制器”一起使用，但描述的信息保真度可能会低于您所习惯的。如果您仅编写Minimal API，并且需要 API Explorer 支持，则需要。IApiDescriptionGroupCollectionProviderIApiDescriptionProviderAddEndpointsApiExplorerAddApiExplorerAddEndpointsApiExplorerAddEndpointsApiExplorer

在 .NET 7.0 中，这两种方法之间的保真度得到了进一步提高。在未来的某个版本中，我们可能会看到这些方法合并为一。

Answer 2

太长了；.AddEndpointsApiExplorer()创建是为了支持Minimal Api 的.

通过 google 搜索文档会显示许多页面，其中包含对.AddEndpointsApiExplorer(). 但没有提及为什么需要它，或者从 v5 项目迁移时是否需要它。文档肯定是缺乏的。

从源代码和git Blame逆向工作，我找到了相关项目。所以答案似乎与对Minimal Api 的支持有关。

我相信创建了一些新服务来从这些新的最小 api 中提取返回类型信息，这种方式在不使用 MVC 的情况下使用端点路由时可能会以更通用的方式应用。

如果您使用 MVC，也许会为您调用.AddControllers()via 。.AddApiExplorer()提供 swagger 所依赖的服务来描述控制器操作。如果这就是您所需要的，那么似乎不需要这个新的 api 调用。

虽然使用swagger和最少 api 的文档包括对.AddEndpointsApiExplorer(). 即使这样也不能准确解释为什么需要它。

为什么会.AddEndpointsApiExplorer()存在？为什么新功能被排除在外.AddApiExplorer()？为什么 v6 的其他文档中没有此方法重命名？

也许我们应该在https://github.com/dotnet/aspnetcore/或https://github.com/dotnet/AspNetCore.Docs/上创建一个问题来要求澄清，这样其他人就不必问这些问题。

Answer 3

长话短说

仅AddEndpointsApiExplorer当您使用 v6 的“最小 API”时才使用，如下所示：

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