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>

API 版本 API 操作 v. API 端點

下列各節說明在 ASP.NET Core 和 OpenAPI 檔中的 API、API 端點和 API 作業之間的差異。

API （應用程式開發介面）

API 是一組規則和通訊協定，可用於建置及與軟體應用程式互動。 它會定義不同的軟體元件應該如何通訊。 在一般 Web 開發中，「API」通常是指透過 HTTP 公開功能的 Web 服務。

在 ASP.NET Core 中，通常會使用控制器或最小 API 來建置 API，以處理傳入的 HTTP 要求和傳回回應。

ASP.NET Core 的內部命名慣例有時會以不同的方式使用 「API」。。 例如，在 API 總管中，“ApiDescription” 實際上代表 API 作業 ，而不是完整的 API 服務。 此差異反映內部命名慣例，有時與這裡所使用的更廣泛定義不同。

如需有關 API Explorer 的詳細資訊，請參閱 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 作業是 OpenAPI 檔的主要焦點。 OpenAPI 規格會依作業來組織檔，這些作業會依路徑 （端點） 分組。 每個作業都會以參數、要求主體、回應等詳細數據來描述。 此結構化格式可讓工具自動產生用戶端連結庫、伺服器存根和互動式檔。

在 OpenAPI 檔中：

• 整個文件將整個 API 描述出來
• 每個路徑項目 （例如 /api/products/{id}） 都代表一個端點
• 在每個路徑下，HTTP 方法 （GET、 POSTPUT、 等） 會定義作業
• 每個作業都包含有關參數、要求本文、回應等的詳細數據。

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 端點之間的差異：

概念	API 操作	API 端點
定義	API 動作的邏輯描述：方法 + 路徑 + 行為	接聽要求的實際設定 HTTP 路由
等級	從概念上看，可能發生的動作有哪些	具體、哪些 URL 和方法相符
連結到	OpenAPI API 設計/規格	在執行時 ASP.NET Core 路由
描述	API 的用途，例如「建立產品」	呼叫它的位置和方式，例如、 POST https://localhost:7099/api/productsPOST https://contoso.com/api/products
在 ASP.NET Core 中	路由解析之前，控制器動作或最小 API 方法	在執行時期解析的端點物件

GitHub 上的 ASP.NET Core OpenAPI 原始程式碼

• AddOpenApi
• OpenApiDocumentService
• OpenApiOptions

其他資源

• 基本 API 中的驗證和授權