OpenAPI ドキュメントを生成する

この Microsoft.AspNetCore.OpenApi パッケージは、ASP.NET Core での OpenAPI ドキュメント生成の組み込みサポートを提供します。 このパッケージでは、次の機能が提供されます。

• 実行時の OpenAPI ドキュメントの生成と、アプリケーション上のエンドポイントを介したアクセスのサポート
• 生成されたドキュメントを変更できる "transformer" API のサポート。
• 1 つのアプリから複数の 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 ドキュメント生成によって、v3.0 の OpenAPI 仕様に準拠したドキュメントが生成されます。 次のコードは、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 ドキュメントに適用できます。 たとえば、次のコードでは、OpenAPI ドキュメントへのアクセスは、tester ロールを持つユーザーに制限されています。

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 ドキュメントの生成。
• Web サーバーから静的に提供される 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 に対して、またはパブリック API と内部 API を区別するために、複数の OpenAPI ドキュメントを出力するように構成できます。 既定では、ビルド時ドキュメント ジェネレーターは、アプリケーションで構成されているすべてのドキュメントのファイルを出力します。 1 つのドキュメント名に対してのみ出力するには、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();
}