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>

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 版本。