ASP.NET Core API 應用程式中的 OpenAPI 支援

ASP.NET Core 支援在控制器型和基本 API 應用程式中產生 OpenAPI 文件。 OpenAPI 規格是記錄 HTTP API 的程式設計語言無關標準。 透過內建 API 和開放原始碼程式庫的組合，在 ASP.NET Core 應用程式中支援此標準。 應用程式中的 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 版本。