【ASP.NET Core Swagger】4、ApiExplorer
介绍
在 ASP.NET Core MVC 应用程序中调用AddMvc()或AddMvcCore()添加的标准服务之一是 ApiExplorer。通过调用services.AddApiExplorer()将 ApiExplorer 服务添加到您的应用程序中
ApiExplorer 功能是Microsoft.AspNetCore.Mvc.ApiExplorer包的一部分。当您在应用程序中包含Microsoft.AspNetCore.Mvc包时，默认情况下会引用此包，因此您通常不需要显式添加该包。如果您从一个精简的应用程序开始，您可以直接添加包以使服务可用。
ApiExplorer 包含用于发现和公开有关 MVC 应用程序的元数据的功能。您可以使用它来提供Controller和Action的详细信息，例如它们的 URL 和允许的 HTTP 方法、参数和响应类型。
您可以使用它为您的应用程序自动生成文档、帮助页面或客户端。Swashbuckle.AspNetCore框架就是使用ApiExplorer 功能来提供一个功能齐全的文档框架。
源码
AddApiExplorer()内部调用方法AddApiExplorerServices()，该方法添加您将在应用程序中使用的服务：
internal static void AddApiExplorerServices(IServiceCollection services)
{
services.TryAddSingleton<IApiDescriptionGroupCollectionProvider, ApiDescriptionGroupCollectionProvider>();
services.TryAddEnumerable(
ServiceDescriptor.Transient<IApiDescriptionProvider, DefaultApiDescriptionProvider>());
}
这会添加一个默认实现，IApiDescriptionGroupCollectionProvider将 API 端点暴露给您的应用程序。要访问 API 列表，您只需将服务注入您的控制器/服务。
读取应用程序的元数据
- 先创建一个简单的Controller
[Route("api/[controller]")]
public class ValuesController : Controller
{
// GET api/values
[HttpGet]
public IEnumerable<string> Get()
{
return new string[] { "value1", "value2" };
}
}
- 创建一个控制器DocumentationController，用于展示Web API 端点的详细信息
注入IApiDescriptionGroupCollectionProvider控制器。为简单起见，我们将直接将其作为模型返回到 Razor 视图页面 - 我们将分解它在 Razor 页面中提供的详细信息。
public class DocumentationController : Controller
{
private readonly IApiDescriptionGroupCollectionProvider _apiExplorer;
public DocumentationController(IApiDescriptionGroupCollectionProvider apiExplorer)
{
_apiExplorer = apiExplorer;
}
public IActionResult Index()
{
return View(_apiExplorer);
}
}
provider公开了一个ApiDescriptionGroups 的集合，每个集合都包含一个ApiDescriptions 的集合。您可以将 anApiDescriptionGroup视为Controller，将 ApiDescription视为Action。
ApiDescription包含有关Action的大量信息 - 参数、URL、可以返回的媒体类型 - 基本上是您可能想知道的有关 API 的所有信息！
下面的 Razor 页面列出了应用程序中公开的所有 API。
@using Microsoft.AspNetCore.Mvc.ApiExplorer;
@model IApiDescriptionGroupCollectionProvider
<div id="body">
<section class="featured">
<div class="content-wrapper">
<hgroup class="title">
<h1>ASP.NET Web API Help Page</h1>
</hgroup>
</div>
</section>
<section class="content-wrapper main-content clear-fix">
<h3>API Groups, version @Model.ApiDescriptionGroups.Version</h3>
@foreach (var group in Model.ApiDescriptionGroups.Items)
{
<h4>@group.GroupName</h4>
<ul>
@foreach (var api in group.Items)
{
<li>
<h5>@api.HttpMethod @api.RelativePath</h5>
<blockquote>
@if (api.ParameterDescriptions.Count > 0)
{
<h6>Parameters</h6>
<dl class="dl-horizontal">
@foreach (var parameter in api.ParameterDescriptions)
{
<dt>Name</dt>
<dd>@parameter.Name, (@parameter.Source.Id)</dd>
<dt>Type</dt>
<dd>@parameter.Type?.FullName</dd>
@if (parameter.RouteInfo != null)
{
<dt>Constraints</dt>
<dd>@string.Join(",", parameter.RouteInfo.Constraints?.Select(c => c.GetType().Name).ToArray())</dd>
<dt>DefaultValue</dt>
<dd>parameter.RouteInfo.DefaultValue</dd>
<dt>Is Optional</dt>
<dd>@parameter.RouteInfo.IsOptional</dd>
}
}
</dl>
}
else
{
<i>No parameters</i>
}
</blockquote>
<blockquote>
<h6>Supported Response Types</h6>
<dl class="dl-horizontal">
@foreach (var response in api.SupportedResponseTypes)
{
<dt>Status Code</dt>
<dd>@response.StatusCode</dd>
<dt>Response Type</dt>
<dd>@response.Type?.FullName</dd>
@foreach (var responseFormat in response.ApiResponseFormats)
{
<dt>Formatter</dt>
<dd>@responseFormat.Formatter?.GetType().FullName</dd>
<dt>Media Type</dt>
<dd>@responseFormat.MediaType</dd>
}
}
</dl>
</blockquote>
</li>
}
</ul>
}
</section>
</div>
如果您现在运行该应用程序，您可能会对响应感到有些惊讶：
参考：
https://andrewlock.net/introduction-to-the-apiexplorer-in-asp-net-core/
