ASP.NET Core API 应用中的 OpenAPI 支持

ASP.NET Core 支持在基于控制器和最小 API 应用中生成 OpenAPI 文档。 OpenAPI 规范是用于记录 HTTP API 的编程语言不可知的标准。 ASP.NET Core 应用通过内置 API 和开源库的组合来支持此标准。 OpenAPI 在应用程序中的集成涉及以下三个关键方面：

• 生成有关应用中终结点的信息。
• 将信息收集为与 OpenAPI 架构匹配的格式。
• 通过可视化 UI 或序列化文件公开生成的 OpenAPI 文档。

ASP.NET Core 应用提供内置支持，用于通过 Microsoft.AspNetCore.OpenApi 包在应用中生成有关终结点的信息。

以下代码由 ASP.NET Core 最小 Web API 模板生成，并使用 OpenAPI：

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

app.UseHttpsRedirection();

var summaries = new[]
{
    "Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
};

app.MapGet("/weatherforecast", () =>
{
    var forecast = Enumerable.Range(1, 5).Select(index =>
        new WeatherForecast
        (
            DateTime.Now.AddDays(index),
            Random.Shared.Next(-20, 55),
            summaries[Random.Shared.Next(summaries.Length)]
        ))
        .ToArray();
    return forecast;
})
.WithName("GetWeatherForecast");

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

在上述突出显示的代码中：

• AddOpenApi 将 OpenAPI 文档生成所需的服务注册到应用程序的 DI 容器中。
• MapOpenApi 在应用程序中添加一个终结点，用于查看序列化为 JSON 的 OpenAPI 文档。 OpenAPI 终结点仅限于开发环境，以最大程度地降低公开敏感信息的风险，并减少生产中的漏洞。

Microsoft.AspNetCore.OpenApi NuGet 包

Microsoft.AspNetCore.OpenApi 包提供以下功能：

• 支持在运行时生成 OpenAPI 文档，并通过应用程序上的终结点访问它们。
• 支持“转换器”API，允许修改生成的文档。

要使用该 Microsoft.AspNetCore.OpenApi 包，请将其作为 PackageReference 添加到项目文件：

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

要详细了解 Microsoft.AspNetCore.OpenApi 包，请参阅生成 OpenAPI 文档。

Microsoft.Extensions.ApiDescription.Server NuGet 包

Microsoft.Extensions.ApiDescription.Server 包支持在生成时生成 OpenAPI 文档并对其进行序列化。

要使用 Microsoft.Extensions.ApiDescription.Server，请将其作为 PackageReference 添加到项目文件。 通过设置 OpenApiGenerateDocuments 属性，可以在生成时生成文档。 默认情况下，生成的 OpenAPI 文档将保存到 obj 目录中，但可以通过设置 OpenApiDocumentsDirectory 属性来自定义输出目录。

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net9.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <PropertyGroup>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.0.*-*" />
    <PackageReference Include="Microsoft.Extensions.ApiDescription.Server" Version="9.0.*-*">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
  </ItemGroup>

</Project>

API v. API操作 v. API 终结点

以下各节介绍了 ASP.NET Core 和 OpenAPI 文档中 API、API 终结点和 API作之间的差异。

API （应用程序编程接口）

API 是一组规则和协议，用于生成软件应用程序并与之交互。 它定义不同的软件组件应如何通信。 在一般 Web 开发中，“API”通常是指通过 HTTP 公开功能的 Web 服务。

在 ASP.NET Core 中，API 通常是使用控制器或最小 API 构建的，这些 API 处理传入的 HTTP 请求和返回响应。

ASP.NET Core 的内部命名约定有时使用不同的“API”。 例如，在 API 资源管理器中，“ApiDescription”实际上表示 API操作，而不是真正完整的 API 服务。 这种区别反映了内部命名约定，有时不同于此处使用的更广泛定义。

有关 API 资源管理器的详细信息，请参阅 ASP.NET Core 中的 ApiExplorer 简介 。

API操作

API操作表示API提供的特定动作或功能。 在 ASP.NET Core 中，对应于：

• MVC 样式 API 中的控制器动作方法
• 最小 API 中的路由处理程序

每个作都由其 HTTP 方法（GET、POSTPUT等）定义，路径、参数和响应。

API 终结点

API 终结点是特定的 URL：

• 表示 API 公开的特定资源或功能。
• 提供客户端需要向其发送 HTTP 请求的确切地址，以便与特定 API作进行交互。

终结点是 API 基 URL 和所需资源的特定路径以及支持的 HTTP 方法的组合：

• 对于基于控制器的 API，终结点将路由模板与控制器和操作组合在一起。
• 对于简化 API，端点使用app.MapGet()、app.MapPost()等显式定义。

例如，api/products/{id} 支持以下操作的终结点：

• GET /api/products/{id}
• PUT /api/products/{id}
• PATCH /api/products/{id}
• Delete /api/products/{id}
• HEAD /api/products/{id}

终结点通常包括查询参数，例如 GET /api/products?category=electronics&sort=price

OpenAPI 文档

在 OpenAPI 的上下文中，文档将 API 描述为一个整体，包括其所有端点和操作。 OpenAPI 提供了一种结构化的方式来记录 API，使开发人员能够更轻松地了解如何与 API 交互。

API操作是 OpenAPI 文档的主要焦点。 OpenAPI 规范按操作组织文档，并按路径（端点）分组。 每个操作都有详细信息，例如参数、请求正文、响应等。 此结构化格式允许工具自动生成客户端库、服务器存根和交互式文档。

在 OpenAPI 文档中：

• 整个文档将 API 描述为整体
• 每个路径项（如 /api/products/{id}）表示终结点
• 在每个路径下，HTTP 方法（GET、POST、PUT等）定义操作。
• 每个操作都包含有关参数、请求正文、响应等的详细信息。

OpenAPI JSON 格式的示例：

json{
  "paths": {
    "/api/products/{id}": {  // This is the endpoint
      "get": {  // This is the operation
        "summary": "Get a product by ID",
        "parameters": [...],
        "responses": {...}
      },
      "put": {  // Another operation on the same endpoint
        "summary": "Update a product",
        "parameters": [...],
        "responses": {...}
      }
    }
  }
}

API、API操作和API终结点比较

下表总结了 API、API作和 API 终结点之间的差异：

GitHub 上的 ASP.NET Core OpenAPI 源代码

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

其他资源

• 最小 API 中的身份验证和授权

OpenAPI 规范是用于记录 HTTP API 的编程语言不可知的标准。 此标准通过通过内置 API 和开放源代码库的组合在最小 API 中获得支持。 OpenAPI 在应用程序中的集成涉及以下三个关键方面：

• 生成有关应用中终结点的信息。
• 将信息收集为与 OpenAPI 架构匹配的格式。
• 通过视觉 UI 或序列化文件公开生成的 OpenAPI 架构。

最小 API 提供内置支持，用于通过 Microsoft.AspNetCore.OpenApi 包生成有关应用中终结点的信息。 通过视觉 UI 公开生成的 OpenAPI 定义需要第三方包。

有关在基于控制器的 API 中对 OpenAPI 的支持的信息，请参阅本文的 .NET 9 版本。