產生 OpenAPI 文件

Microsoft.AspNetCore.OpenApi 套件提供在 ASP.NET Core 中產生 OpenAPI 文件的內建支援。 PPL 提供下列功能：

• 支援在執行階段產生 OpenAPI 文件，並透過應用程式上的端點加以存取。
• 支援允許修改所產生文件的「轉換器」API。
• 支援從單一應用程式產生多個 OpenAPI 檔。
• 利用 System.Text.Json 所提供的 JSON 結構描述支援。
• 與原生 AoT 相容。

套件安裝

安裝 Microsoft.AspNetCore.OpenApi 套件：

Visual Studio

從封裝管理員主控台執行下列命令：

Install-Package Microsoft.AspNetCore.OpenApi

.NET CLI

執行以下命令：

dotnet add package Microsoft.AspNetCore.OpenApi

設定 OpenAPI 文件產生

下列程式碼範例：

• 新增 OpenAPI 服務。
• 啟用端點以檢視 JSON 格式的 OpenAPI 文件。

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello world!");

app.Run();

啟動應用程式並瀏覽至 https://localhost:<port>/openapi/v1.json，以檢視產生的 OpenAPI 文件。

自訂 OpenAPI 文件產生的選項

下列各節示範如何自訂 OpenAPI 文件產生。

自訂 OpenAPI 文件名稱

應用程式中的每份 OpenAPI 文件都有唯一的名稱。 註冊的預設文件名稱為 v1。

builder.Services.AddOpenApi(); // Document name is v1

藉由將文件名稱當做參數傳遞至 AddOpenApi 呼叫，即可修改該名稱。

builder.Services.AddOpenApi("internal"); // Document name is internal

文件名稱會呈現在 OpenAPI 實作的數個位置中。

擷取產生的 OpenAPI 文件時，文件名稱會在要求中以 documentName 參數引數的形式提供。 下列要求會解析 v1 和 internal 文件。

GET http://localhost:5000/openapi/v1.json
GET http://localhost:5000/openapi/internal.json

自訂所產生文件的 OpenAPI 版本

根據預設，OpenAPI 文件產生會建立一份符合 OpenAPI 規格 v3.0 的文件。 下列程式碼示範如何修改 OpenAPI 文件的預設版本：

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi2_0;
});

自訂 OpenAPI 端點路由

根據預設，透過呼叫 MapOpenApi 註冊的 OpenAPI 端點會在 /openapi/{documentName}.json 端點公開文件。 下列程式碼示範如何自訂 OpenAPI 文件註冊所在的路由：

app.MapOpenApi("/openapi/{documentName}/openapi.json");

從端點路由中移除 documentName 路由參數是可行的，但不建議這麼做。 當 documentName 路由參數從端點路由中移除時，架構會嘗試從查詢參數中解析文件名稱。 未在路由或查詢中提供 documentName 可能會導致非預期的行為。

自訂 OpenAPI 端點

由於 OpenAPI 文件是透過路由處理常式端點提供服務的，因此可用於標準最低端點的任何自訂也可用於 OpenAPI 端點。

限制授權使用者才能存取 OpenAPI 文件

OpenAPI 端點預設不會啟用任何授權檢查。 不過，授權檢查可以套用至 OpenAPI 文件。 例如，在下列程式碼中，限制具有 tester 角色的人員才能存取 OpenAPI 文件：

using Microsoft.AspNetCore.Authentication;
using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddAuthentication().AddJwtBearer();
builder.Services.AddAuthorization(o =>
{
    o.AddPolicy("ApiTesterPolicy", b => b.RequireRole("tester"));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi()
    .RequireAuthorization("ApiTesterPolicy");

app.MapGet("/", () => "Hello world!");

app.Run();

快取產生的 OpenAPI 文件

每次向 OpenAPI 端點傳送要求時，都會重新產生 OpenAPI 文件。 重新產生可讓轉換器將動態應用程式狀態納入其作業中。 例如，使用 HTTP 內容的詳細資料重新產生要求。 如果適用，可以快取 OpenAPI 文件，以避免在每個 HTTP 要求上執行文件產生管線。

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.OpenApi;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOutputCache(options =>
{
    options.AddBasePolicy(policy => policy.Expire(TimeSpan.FromMinutes(10)));
});
builder.Services.AddOpenApi();

var app = builder.Build();

app.UseOutputCache();

app.MapOpenApi()
    .CacheOutput();

app.MapGet("/", () => "Hello world!");

app.Run();

在建置階段產生 OpenAPI 檔

在一般 Web 應用程式中，OpenAPI 檔會在運行時間產生，並透過 HTTP 要求提供給應用程式伺服器。

在某些情況下，在應用程式的建置步驟期間產生 OpenAPI 檔會很有説明。 這些案例包括：

• 產生認可至原始檔控制的 OpenAPI 檔。
• 產生用於規格整合測試的 OpenAPI 檔。
• 從網頁伺服器產生靜態提供的 OpenAPI 檔。

若要新增在組建階段產生 OpenAPI 文件的支援，請安裝 Microsoft.Extensions.ApiDescription.Server 封裝：

Visual Studio

從封裝管理員主控台執行下列命令：

Install-Package Microsoft.Extensions.ApiDescription.Server

.NET CLI

從包含專案檔的目錄中執行下列命令：

dotnet add package Microsoft.Extensions.ApiDescription.Server

安裝時，此套件會在建置期間自動產生與應用程式相關聯的Open API檔，並將其填入應用程式的輸出目錄中。

$ dotnet build
$ cat bin/Debug/net9.0/{ProjectName}.json

自定義建置時間檔產生

修改所產生 Open API 檔案的輸出目錄

根據預設，產生的 OpenAPI 檔案會發出至應用程式的輸出目錄。 若要修改發出檔案的位置，請在 屬性中 OpenApiDocumentsDirectory 設定目標路徑。

<PropertyGroup>
  <OpenApiDocumentsDirectory>./</OpenApiDocumentsDirectory>
</PropertyGroup>

的值 OpenApiDocumentsDirectory 會相對於項目檔解析。 ./使用上述值，將會在與項目檔相同的目錄中發出 OpenAPI 檔。

修改輸出檔名

根據預設，產生的 OpenAPI 檔的名稱會與應用程式的項目檔相同。 若要修改發出的檔名，請在 屬性中OpenApiGenerateDocumentsOptions設定 --file-name 自變數。

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--file-name my-open-api</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

選取要產生的 OpenAPI 檔

某些應用程式可能會設定為針對各種 API 版本發出多個 OpenAPI 檔，或區分公用和內部 API。 根據預設，建置時間檔產生器會針對應用程式中設定的所有檔案發出檔案。 若要只針對單一檔名稱發出，請在屬性中OpenApiGenerateDocumentsOptions設定 --document-name 自變數。

<PropertyGroup>
  <OpenApiGenerateDocumentsOptions>--document-name v2</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

在建置時間檔產生期間自定義運行時間行為

在建置時間 OpenAPI 檔案產生函式的幕後，使用插入伺服器實作啟動應用程式的進入點。 這是產生正確 OpenAPI 檔的需求，因為無法以靜態方式分析 OpenAPI 檔中的所有資訊。 由於叫用應用程式的進入點，因此會叫用應用程式啟動時的任何邏輯。 這包括將服務插入 DI 容器或從組態讀取的程式代碼。 在某些情況下，必須限制從建置時間檔產生叫用應用程式進入點時執行的程式碼路徑。 這些案例包括：

• 未從特定組態字串讀取。
• 未註冊資料庫相關服務。

為了限制這些程式代碼路徑不受建置時間產生管線叫用，這些程式代碼路徑可以在專案元件的檢查後方設定條件，如下所示：

using System.Reflection;

var builder = WebApplication.CreateBuilder();

if (Assembly.GetEntryAssembly()?.GetName().Name != "GetDocument.Insider")
{
  builder.Services.AddDefaults();
}