OpenAPI ドキュメントの操作

[アーティクル]
08/27/2024

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

実行時の OpenAPI ドキュメントの生成と、アプリケーション上のエンドポイントを介したアクセスのサポート
生成されたドキュメントを変更できる "transformer" API のサポート。
1 つのアプリから複数の OpenAPI ドキュメントを生成するためのサポート。
System.Text.Json によって提供される JSON スキーマのサポートを利用します。
ネイティブ AoT と互換性があります。

パッケージインストール

Microsoft.AspNetCore.OpenApi パッケージのインストール:

Visual Studio
.NET CLI

パッケージマネージャーコンソールから、次のコマンドを実行します。

Install-Package Microsoft.AspNetCore.OpenApi -IncludePrerelease

次のコマンドを実行します。

dotnet add package Microsoft.AspNetCore.OpenApi --prerelease

ビルド時に OpenAPI ドキュメントを生成するためのサポートを追加するには、Microsoft.Extensions.ApiDescription.Server パッケージをインストールします。

Visual Studio
.NET CLI

パッケージマネージャーコンソールから、次のコマンドを実行します。

Install-Package Microsoft.Extensions.ApiDescription.Server -IncludePrerelease

プロジェクトファイルが含まれているディレクトリで次のコマンドを実行します。

dotnet add package Microsoft.Extensions.ApiDescription.Server --prerelease

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 ドキュメントを表示します。

ASP.NET Web アプリに OpenAPI メタデータを含む

ASP.NET は、Web アプリのエンドポイントからメタデータを収集し、それを使用して OpenAPI ドキュメントを生成します。コントローラーベースのアプリでは、メタデータは [EndpointDescription]、[HttpPost]、[Produces] などの属性から収集されます。 Minimal API では、メタデータは属性から収集できますが、ルートハンドラーから TypedResults を返すなどの拡張メソッドやその他の戦略を使用して設定することもできます。次の表に、収集されるメタデータと、それを設定するための戦略の概要を示します。

Metadata	Attribute	拡張メソッド	その他の戦略
まとめ	`[EndpointSummary]`	`WithSummary`
description	`[EndpointDescription]`	`WithDescription`
tags	`[Tags]`	`WithTags`
operationId	`[EndpointName]`	`WithName`
parameters	`[FromQuery]`、`[FromRoute]`、`[FromHeader]`、`[FromForm]`
パラメーターの説明	`[Description]`
requestBody	`[FromBody]`	`Accepts`
responses	`[Produces]`、`[ProducesProblem]`	`Produces`、`ProducesProblem`	`TypedResults`
エンドポイントの除外	`[ExcludeFromDescription]`	`ExcludeFromDescription`

ASP.NET Core では、XML ドキュメントのコメントからメタデータは収集されません。

次のセクションでは、生成された OpenAPI ドキュメントをカスタマイズするためにアプリにメタデータを含める方法を示します。

要約と説明

エンドポイントの概要と説明は、[EndpointSummary] 属性と [EndpointDescription] 属性を使用して、または Minimal API で、WithSummary と WithDescription 拡張メソッドを使用して設定できます。

[EndpointSummary]: EndpointSummaryAttribute
[EndpointDescription]: EndpointDescriptionAttribute
WithSummary: WithSummary
WithDescription: WithDescription

最小 API
コントローラー

次のサンプルでは、概要と説明を設定するためのさまざまな方法を示します。

属性は app.MapGet メソッドではなくデリゲートメソッドに配置されることに注意してください。

app.MapGet("/extension-methods", () => "Hello world!")
  .WithSummary("This is a summary.")
  .WithDescription("This is a description.");

app.MapGet("/attributes",
  [EndpointSummary("This is a summary.")]
  [EndpointDescription("This is a description.")]
  () => "Hello world!");

次のサンプルでは、概要と説明を設定する方法を示します。

  [EndpointSummary("This is a summary.")]
  [EndpointDescription("This is a description.")]
  [HttpGet("attributes")]
  public IResult Attributes()
  {
      return Results.Ok("Hello world!");
  }

operationId

OpenAPI では、操作の一意の識別子または名前として、各エンドポイントの operationId がサポートされています。コントローラーベースのアプリでは、[EndpointName] 属性を使用して operationId を設定できます。 Minimal API では、[EndpointName] 属性または WithName 拡張メソッドを使用して operationId を設定できます。

[EndpointName]: EndpointNameAttribute
WithName: WithName

最小 API
コントローラー

次のサンプルでは、タグを設定するためのさまざまな方法を示します。

app.MapGet("/extension-methods", () => "Hello world!")
  .WithName("FromExtensionMethods");

app.MapGet("/attributes",
  [EndpointName("FromAttributes")]
  () => "Hello world!");

次のサンプルでは、operationId を設定する方法を示します。

  [EndpointName("FromAttributes")]
  [HttpGet("attributes")]
  public IResult Attributes()
  {
      return Results.Ok("Hello world!");
  }

parameters

OpenAPI では、API によって使用されるパス、クエリ文字列、ヘッダー、cookie パラメーターの注釈付けをサポートします。

フレームワークは、ルートハンドラーのシグネチャに基づいて、要求パラメーターの型を自動的に推論します。

[Description] 属性を使用して、パラメーターの説明を指定できます。

Description

最小 API
コントローラー

次のサンプルでは、パラメーターの説明を設定する方法を示します。

app.MapGet("/attributes",
  ([Description("This is a description.")] string name) => "Hello world!");

次のサンプルでは、パラメーターの説明を設定する方法を示します。

  [HttpGet("attributes")]
  public IResult Attributes([Description("This is a description.")] string name)
  {
      return Results.Ok("Hello world!");
  }

requestBody

要求本文として送信される入力の型を定義するには、Accepts 拡張メソッドを使ってプロパティを構成し、要求ハンドラーで想定されるオブジェクトの種類とコンテンツタイプを定義します。次の例では、エンドポイントは要求本文で Todo オブジェクトを受け入れ、想定されるコンテンツタイプは application/xml となります。

app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
  .Accepts<Todo>("application/xml");

Accepts 拡張メソッドに加えて、IEndpointParameterMetadataProvider インターフェイスを実装することで、パラメーター型がそれ自身の注釈を記述できます。たとえば、次の Todo 型は application/xml コンテンツタイプを持つ要求本文を必要とする注釈を追加します。

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new AcceptsMetadata(["application/xml", "text/xml"], typeof(XmlBody)));
    }
}

明示的な注釈が提供されない場合、フレームワークは、エンドポイントハンドラーに要求本文パラメーターがあれば、既定の要求の型を決定しようとします。推論では、次のヒューリスティックを使って注釈が生成されます。

[FromForm] 属性によってフォームから読み込まれる要求本文パラメーターは、multipart/form-data コンテンツタイプで記述されます。
他のすべての要求本文パラメーターは application/json コンテンツタイプで記述されます。
要求本文が Null 許容であるか、AllowEmpty プロパティが FromBody 属性に設定されている場合は、省略可能として扱われます。

応答の種類の説明

OpenAPI では、API から返される応答の記述を提供できます。 Minimal API は、エンドポイントの応答の型を設定するための 3 つの方法をサポートしています。

エンドポイント上の Produces 拡張メソッドによる方法。
ルートハンドラーの ProducesResponseType 属性を使う方法。
ルートハンドラーから TypedResults を返す方法。

Produces 拡張メソッドを使って、エンドポイントに Produces メタデータを追加できます。パラメーターが指定されていない場合、拡張メソッドは 200 状態コードと application/json コンテンツタイプの下で対象となる型のメタデータを設定します。

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
  .Produces<IList<Todo>>();

エンドポイントのルートハンドラーの実装で TypedResults を使用すると、エンドポイントに対する応答の型のメタデータが自動的に含まれます。たとえば、以下のコードは、application/json コンテンツタイプでの 200 状態コードの応答で、エンドポイントに自動的に注釈を付けます。

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync();
    return TypedResults.Ok(todos);
});

`ProblemDetails` の応答を設定する

ProblemDetails 応答を返す可能性があるエンドポイントの応答の種類を設定する場合、ProducesProblem メソッドまたは ProducesValidationProblem 拡張メソッドまたは TypedResults.Problem を使用して、エンドポイントのメタデータに適切な注釈を追加できます。

これらのいずれかの方法で明示的な注釈が提供されていない場合、フレームワークは応答のシグネチャを調べることによって、既定の応答の型を決定しようとします。この既定の応答は、OpenAPI 定義の 200 状態コードの下に設定されます。

複数応答の種類

エンドポイントがさまざまなシナリオでさまざまな種類の応答を返すことができる場合は、次の方法でメタデータを指定できます。

次の例に示すように、Produces 拡張メソッドを複数回呼び出します。

app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

次の例に示すように、シグネチャで Results<TResult1,TResult2,TResultN> を、ハンドラーの本体で TypedResults を使用します。
```
app.MapGet("/book{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) =>
{
    return bookList.FirstOrDefault((i) => i.Id == id) is Book book
     ? TypedResults.Ok(book)
     : TypedResults.NotFound();
});
```
Results<TResult1,TResult2,TResultN> 共用体型は、ルートハンドラーが IResult を実装する複数の具象型を返し、IEndpointMetadataProvider を実装するそれらの型はいずれもエンドポイントのメタデータに寄与することを宣言します。

共用体型は、暗黙的なキャスト演算子を実装します。これらの演算子により、コンパイラはジェネリック引数で指定されている型を共用体型のインスタンスに自動的に変換できるようになります。この機能にはさらに、ルートハンドラーからそうすることが宣言されている結果のみが返されることがコンパイル時にチェックされるという利点があります。ジェネリック引数の 1 つとして宣言されていない型を Results<TResult1,TResult2,TResultN> に返そうとすると、コンパイルエラーが発生します。

生成されたドキュメントからのエンドポイントの除外

既定では、アプリで定義されているすべてのエンドポイントは、生成された OpenAPI ファイルに記載されています。 Minimal API は、次を使用して、特定のエンドポイントを OpenAPI ドキュメントから除外する戦略をサポートします。

次のサンプルでは、生成された OpenAPI ドキュメントから指定されたエンドポイントを除外するためのさまざまな方法を示します。

app.MapGet("/extension-method", () => "Hello world!")
  .ExcludeFromDescription();

app.MapGet("/attributes",
  [ExcludeFromDescription]
  () => "Hello world!");

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 ドキュメントのトランスフォーマー

このセクションでは、トランスフォーマーを使用して OpenAPI ドキュメントをカスタマイズする方法について説明します。

トランスフォーマーを使用して OpenAPI ドキュメントをカスタマイズする

トランスフォーマーは、ユーザー定義のカスタマイズによって OpenAPI ドキュメントを変更するための API を提供します。トランスフォーマーは、次のようなシナリオに役立ちます。

ドキュメント内のすべての操作にパラメーターを追加する。
パラメーターまたは操作の説明を変更する。
OpenAPI ドキュメントに最上位の情報を追加する。

トランスフォーマーは、次の 2 つのカテゴリに分類されます。

ドキュメントトランスフォーマーは、OpenAPI ドキュメント全体にアクセスできます。これらを使用して、ドキュメントをグローバルに変更できます。
操作トランスフォーマーは、個々の操作に適用されます。個々の各操作は、パスと HTTP メソッドの組み合わせです。これらを使用して、エンドポイントのパラメーターまたは応答を変更できます。

トランスフォーマーは、OpenApiOptions オブジェクトの AddDocumentTransformer メソッドを呼び出してドキュメントに登録できます。次のスニペットは、トランスフォーマーをドキュメントに登録するさまざまな方法を示しています。

デリゲートを使用してドキュメントトランスフォーマーを登録する。
IOpenApiDocumentTransformer のインスタンスを使用してドキュメントトランスフォーマーを登録する。
DI によってアクティブ化される IOpenApiDocumentTransformer を使用してドキュメントトランスフォーマーを登録する。
デリゲートを使用して操作トランスフォーマーを登録する。
IOpenApiOperationTransformer のインスタンスを使用して操作トランスフォーマーを登録する。
DI によってアクティブ化される IOpenApiOperationTransformer を使用して操作トランスフォーマーを登録する。
デリゲートを使用してスキーマトランスフォーマーを登録する。
IOpenApiSchemaTransformer のインスタンスを使用してスキーマトランスフォーマーを登録する。
DI によってアクティブ化される IOpenApiSchemaTransformer を使用してスキーマトランスフォーマーを登録する。

using Microsoft.AspNetCore.OpenApi;
using Microsoft.OpenApi.Models;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) 
                             => Task.CompletedTask);
    options.AddDocumentTransformer(new MyDocumentTransformer());
    options.AddDocumentTransformer<MyDocumentTransformer>();
    options.AddOperationTransformer((operation, context, cancellationToken)
                            => Task.CompletedTask);
    options.AddOperationTransformer(new MyOperationTransformer());
    options.AddOperationTransformer<MyOperationTransformer>();
    options.AddSchemaTransformer((schema, context, cancellationToken)
                            => Task.CompletedTask);
    options.AddSchemaTransformer(new MySchemaTransformer());
    options.AddSchemaTransformer<MySchemaTransformer>();
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

トランスフォーマーの実行順序

トランスフォーマーは、登録に基づいて先入れ先出し順に実行されます。次のスニペットでは、ドキュメントトランスフォーマーは、操作トランスフォーマーによって行われた変更にアクセスできます。

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
    options.AddOperationTransformer((operation, context, cancellationToken)
                                     => Task.CompletedTask);
    options.AddDocumentTransformer((document, context, cancellationToken)
                                     => Task.CompletedTask);
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

ドキュメントトランスフォーマーを使用する

ドキュメントトランスフォーマーは、次を含むコンテキストオブジェクトにアクセスできます。

変更するドキュメントの名前。
そのドキュメントに関連付けられている ApiDescriptionGroups の一覧。
ドキュメントの生成で使用される IServiceProvider。

ドキュメントトランスフォーマーは、生成された OpenAPI ドキュメントを変化させることもできます。次の例は、API に関する情報を OpenAPI ドキュメントに追加するドキュメントトランスフォーマーを示しています。

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

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info = new()
        {
            Title = "Checkout API",
            Version = "v1",
            Description = "API for processing checkouts from cart."
        };
        return Task.CompletedTask;
    });
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

サービスによってアクティブ化されたドキュメントトランスフォーマーは、DI のインスタンスを利用してアプリを変更できます。次のサンプルでは、認証層から IAuthenticationSchemeProvider サービスを使用するドキュメントトランスフォーマーを示します。 JWT ベアラー関連のスキームがアプリに登録されているかどうかを確認し、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.AddOpenApi(options =>
{
    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            var requirements = new Dictionary<string, OpenApiSecurityScheme>
            {
                ["Bearer"] = new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer", // "bearer" refers to the header name here
                    In = ParameterLocation.Header,
                    BearerFormat = "Json Web Token"
                }
            };
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes = requirements;
        }
    }
}

ドキュメントトランスフォーマーは、関連付けられているドキュメントインスタンスに固有です。次の例では、トランスフォーマーは以下を実行します。

認証関連の要件を internal ドキュメントに登録します。
public ドキュメントは変更されません。

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.AddOpenApi("internal", options =>
{
    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});
builder.Services.AddOpenApi("public");

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/world", () => "Hello world!")
    .WithGroupName("internal");
app.MapGet("/", () => "Hello universe!")
    .WithGroupName("public");

app.Run();

internal sealed class BearerSecuritySchemeTransformer(IAuthenticationSchemeProvider authenticationSchemeProvider) : IOpenApiDocumentTransformer
{
    public async Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
    {
        var authenticationSchemes = await authenticationSchemeProvider.GetAllSchemesAsync();
        if (authenticationSchemes.Any(authScheme => authScheme.Name == "Bearer"))
        {
            // Add the security scheme at the document level
            var requirements = new Dictionary<string, OpenApiSecurityScheme>
            {
                ["Bearer"] = new OpenApiSecurityScheme
                {
                    Type = SecuritySchemeType.Http,
                    Scheme = "bearer", // "bearer" refers to the header name here
                    In = ParameterLocation.Header,
                    BearerFormat = "Json Web Token"
                }
            };
            document.Components ??= new OpenApiComponents();
            document.Components.SecuritySchemes = requirements;

            // Apply it as a requirement for all operations
            foreach (var operation in document.Paths.Values.SelectMany(path => path.Operations))
            {
                operation.Value.Security.Add(new OpenApiSecurityRequirement
                {
                    [new OpenApiSecurityScheme { Reference = new OpenApiReference { Id = "Bearer", Type = ReferenceType.SecurityScheme } }] = Array.Empty<string>()
                });
            }
        }
    }
}

操作トランスフォーマーを使用する

操作は、OpenAPI ドキュメント内の HTTP パスとメソッドの一意の組み合わせです。操作トランスフォーマーは、次の変更を行うときに役立ちます。

アプリ内の各エンドポイントに対して行う必要があります。または
特定のルートに条件付きで適用されます。

操作トランスフォーマーは、次を含むコンテキストオブジェクトにアクセスできます。

操作が属するドキュメントの名前。
操作に関連付けられた ApiDescription。
ドキュメントの生成で使用される IServiceProvider。

たとえば、次の操作トランスフォーマーは、ドキュメント内のすべての操作でサポートされる応答状態コードとして 500 を追加します。

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.AddOpenApi(options =>
{
    options.AddOperationTransformer((operation, context, cancellationToken) =>
    {
        operation.Responses.Add("500", new OpenApiResponse { Description = "Internal server error" });
        return Task.CompletedTask;
    });
});

var app = builder.Build();

app.MapOpenApi();

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

app.Run();

生成された OpenAPI ドキュメントの使用

OpenAPI ドキュメントは、テスト、ドキュメント、ローカル開発のための既存のツールの幅広いエコシステムに接続できます。

ローカルのアドホックテストに Swagger UI を使用する

既定では、Microsoft.AspNetCore.OpenApi パッケージには、OpenAPI ドキュメントを視覚化または操作するための組み込みサポートは付属していません。 OpenAPI ドキュメントを視覚化または操作するための一般的なツールとして、Swagger UI と ReDoc があります。 Swagger UI と ReDoc は、いくつかの方法でアプリに統合できます。 Visual Studio や VS Code などのエディターには、OpenAPI ドキュメントに対するテスト用の拡張機能と組み込みのエクスペリエンスが用意されています。

Swashbuckle.AspNetCore.SwaggerUi パッケージには、アプリで使用するための Swagger UI の Web アセットのバンドルが用意されています。このパッケージを使用して、生成されたドキュメントの UI をレンダリングできます。これを構成するには、Swashbuckle.AspNetCore.SwaggerUi パッケージをインストールします。

先ほど登録した OpenAPI ルートを参照して swagger-ui ミドルウェアを有効にします。情報漏えいとセキュリティの脆弱性を制限するために、"開発環境でのみ Swagger UI を有効にする" ことをお勧めします。

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.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();
if (app.Environment.IsDevelopment())
{
    app.UseSwaggerUI(options =>
    {
        options.SwaggerEndpoint("/openapi/v1.json", "v1");
    });

}

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

app.Run();

対話型 API ドキュメントへの Scalar の使用

Scalar は、OpenAPI 用のオープンソースの対話型ドキュメント UI です。 Scalar は、ASP.NET Core によって提供される OpenAPI エンドポイントと統合できます。 Scalar を構成するには、Scalar.AspNetCore パッケージをインストールします。

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

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

if (app.Environment.IsDevelopment())
{
    app.MapScalarApiReference();
}

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

app.Run();

生成された OpenAPI ドキュメントの Spectral によるリンティング

Spectral は、オープンソースの OpenAPI ドキュメントリンターです。 Spectral をアプリビルドに組み込んで、生成された OpenAPI ドキュメントの品質を検証できます。パッケージのインストール手順に従って Spectral をインストールしてください。

Spectral を利用するには、Microsoft.Extensions.ApiDescription.Server パッケージをインストールして、ビルド時の OpenAPI ドキュメント生成を有効にします。

アプリの .csproj ファイルで次のプロパティを設定して、ビルド時のドキュメント生成を有効にします。

<PropertyGroup>
    <OpenApiDocumentsDirectory>$(MSBuildProjectDirectory)</OpenApiDocumentsDirectory>
    <OpenApiGenerateDocuments>true</OpenApiGenerateDocuments>
</PropertyGroup>

dotnet build を実行して、ドキュメントを生成します。

dotnet build

次の内容を持つ新しいファイル .spectral.yml を作成します。

extends: ["spectral:oas"]

生成されたファイルで spectral lint を実行します。

spectral lint WebMinOpenApi.json
...

The output shows any issues with the OpenAPI document.

```output
1:1  warning  oas3-api-servers       OpenAPI "servers" must be present and non-empty array.
3:10  warning  info-contact           Info object must have "contact" object.                        info
3:10  warning  info-description       Info "description" must be present and non-empty string.       info
9:13  warning  operation-description  Operation "description" must be present and non-empty string.  paths./.get
9:13  warning  operation-operationId  Operation must have "operationId".                             paths./.get

✖ 5 problems (0 errors, 5 warnings, 0 infos, 0 hints)

Minimal API は、Microsoft.AspNetCore.OpenApi パッケージを使ってアプリ内のエンドポイントに関する情報を生成するための組み込みサポートを提供します。生成された OpenAPI 定義をビジュアル UI で表示するには、サードパーティ製のパッケージが必要です。コントローラーベースの API での OpenAPI のサポートについては、この記事の「.NET 9 バージョン」をご覧ください。

次のコードは、ASP.NET Core の最小限の Web API テンプレートによって生成され、OpenAPI が使用されます。

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

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")
.WithOpenApi();

app.Run();

internal record WeatherForecast(DateTime Date, int TemperatureC, string? Summary)
{
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}

前の強調表示されたコードでは、次のようになっています。

Microsoft.AspNetCore.OpenApi については、次のセクションで説明します。
AddEndpointsApiExplorer : API Explorer を使用して、既定の注釈によってエンドポイントを検出して記述するようにアプリを構成します。 WithOpenApi は、一致する、API Explorer によって生成された既定の注釈を、Microsoft.AspNetCore.OpenApi パッケージから生成された注釈でオーバーライドします。
UseSwagger は Swagger ミドルウェアを追加します。
`UseSwaggerUI` により、Swagger UI ツールの埋め込みバージョンが有効になります。
WithName: エンドポイントの IEndpointNameMetadata はリンク生成に使用され、指定されたエンドポイントの OpenAPI 仕様の操作 ID として扱われます。
WithOpenApi については、この記事で後ほど説明します。

`Microsoft.AspNetCore.OpenApi` NuGet パッケージ

ASP.NET Core では、エンドポイントの OpenAPI 仕様と対話するための Microsoft.AspNetCore.OpenApi パッケージが提供されます。このパッケージは、Microsoft.AspNetCore.OpenApi パッケージで定義されている OpenAPI モデルと、Minimal API で定義されているエンドポイント間のリンクとして機能します。このパッケージには、エンドポイントのパラメーター、応答、メタデータを調べて、エンドポイントを記述するために使用される OpenAPI 注釈の種類を構築する API が用意されています。

Microsoft.AspNetCore.OpenApi は PackageReference としてプロジェクトファイルに追加されます。

<Project Sdk="Microsoft.NET.Sdk.Web">

  <PropertyGroup>
    <TargetFramework>net7.0</TargetFramework>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>

  <ItemGroup>    
    <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="7.0.*-*" />
    <PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0" />
  </ItemGroup>

</Project>

Microsoft.AspNetCore.OpenApi で Swashbuckle.AspNetCore を使用する場合は、Swashbuckle.AspNetCore 6.4.0 以降を使用する必要があります。 WithOpenApi 呼び出しでコピーコンストラクターを活用するには、Microsoft.OpenApi 1.4.3 以降を使用する必要があります。

`WithOpenApi` によるエンドポイントへの OpenAPI 注釈の追加

エンドポイント上で WithOpenApi を呼び出すと、エンドポイントのメタデータに追加されます。このメタデータは:

Swashbuckle.AspNetCore などのサードパーティ製パッケージで使用できます。
Swagger ユーザーインターフェイスや、API を定義するために生成された YAML や JSON で表示できます。

app.MapPost("/todoitems/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi();

`WithOpenApi` の OpenAPI 注釈を変更する

WithOpenApi メソッドには、OpenAPI 注釈の変更に使用できる関数を指定できます。たとえば、次のコードでは、エンドポイントの最初のパラメーターに記述が追加されています。

app.MapPost("/todo2/{id}", async (int id, Todo todo, TodoDb db) =>
{
    todo.Id = id;
    db.Todos.Add(todo);
    await db.SaveChangesAsync();

    return Results.Created($"/todoitems/{todo.Id}", todo);
})
.WithOpenApi(generatedOperation =>
{
    var parameter = generatedOperation.Parameters[0];
    parameter.Description = "The ID associated with the created Todo";
    return generatedOperation;
});

OpenAPI に操作 ID を追加する

操作 ID は、OpenAPI において指定されたエンドポイントを一意に識別するために使われます。 WithName 拡張メソッドを使うと、メソッドに使われる操作 ID を設定できます。

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

または、OpenAPI 注釈で OperationId プロパティを直接設定することもできます。

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        OperationId = "GetTodos"
    });

OpenAPI の記述にタグを追加する

OpenAPI では、タグオブジェクトを使った操作の分類をサポートしています。これらのタグは、通常、Swagger UI で操作をグループ化するために使われます。必要なタグを持つエンドポイント上で WithTags 拡張メソッドを呼び出すことにより、これらのタグを操作に追加できます。

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");

または、WithOpenApi 拡張メソッドを使って、OpenApiTags の一覧を OpenAPI 注釈に設定することもできます。

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Tags = new List<OpenApiTag> { new() { Name = "Todos" } }
    });

エンドポイントの概要または説明を追加する

エンドポイントの概要と説明は、WithOpenApi 拡張メソッドを呼び出すことによって追加できます。次のコードでは、OpenAPI 注釈に概要を直接設定しています。

app.MapGet("/todoitems2", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Summary = "This is a summary",
        Description = "This is a description"
    });

OpenAPI の記述を除外する

次のサンプルでは、OpenAPI の説明の生成から /skipme エンドポイントが除外されます。

using Microsoft.AspNetCore.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();

app.MapGet("/swag", () => "Hello Swagger!")
    .WithOpenApi();
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

API を古いものとしてマークする

エンドポイントを古いものとしてマークするには、OpenAPI 注釈に Deprecated プロパティを設定します。

app.MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .WithOpenApi(operation => new(operation)
    {
        Deprecated = true
    });

応答の種類の説明

エンドポイント上の Produces 拡張メソッドによる方法
ルートハンドラーの ProducesResponseType 属性を使う方法
ルートハンドラーから TypedResults を返す方法

app
    .MapGet("/todos", async (TodoDb db) => await db.Todos.ToListAsync())
    .Produces<IList<Todo>>();

エンドポイントのルートハンドラーの実装で TypedResults を使用すると、エンドポイントに対する応答の型のメタデータが自動的に含まれます。たとえば、以下のコードは、application/json コンテンツタイプでの 200 状態コードの応答で、エンドポイントに自動的に注釈を付けます。

app.MapGet("/todos", async (TodoDb db) =>
{
    var todos = await db.Todos.ToListAsync());
    return TypedResults.Ok(todos);
});

`ProblemDetails` の応答を設定する

ProblemDetails 応答を返す可能性があるエンドポイントの応答の種類を設定する場合、ProducesProblem の拡張メソッドである ProducesValidationProblem、または TypedResults.Problem を使用して、エンドポイントのメタデータに適切な注釈を追加できます。 ProducesProblem と ProducesValidationProblem の拡張メソッドは、.NET 8 以前のルートグループでは使用できないことに注意してください。

上記のいずれかの方法で明示的な注釈が提供されていない場合、フレームワークは応答のシグネチャを調べることによって、既定の応答の型を決定しようとします。この既定の応答は、OpenAPI 定義の 200 状態コードの下に設定されます。

複数応答の種類

エンドポイントがさまざまなシナリオでさまざまな種類の応答を返すことができる場合は、次の方法でメタデータを指定できます。

次の例に示すように、Produces 拡張メソッドを複数回呼び出します。

app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

次の例に示すように、シグネチャで Results<TResult1,TResult2,TResultN> を、ハンドラーの本体で TypedResults を使用します。
```
app.MapGet("/book{id}", Results<Ok<Book>, NotFound> (int id, List<Book> bookList) =>
{
    return bookList.FirstOrDefault((i) => i.Id == id) is Book book
     ? TypedResults.Ok(book)
     : TypedResults.NotFound();
});
```
Results<TResult1,TResult2,TResultN> 共用体型は、ルートハンドラーが IResult を実装する複数の具象型を返し、IEndpointMetadataProvider を実装するそれらの型はいずれもエンドポイントのメタデータに寄与することを宣言します。

共用体型は、暗黙的なキャスト演算子を実装します。これらの演算子により、コンパイラはジェネリック引数で指定されている型を共用体型のインスタンスに自動的に変換できるようになります。この機能にはさらに、ルートハンドラーからそうすることが宣言されている結果のみが返されることがコンパイル時にチェックされるという利点があります。ジェネリック引数の 1 つとして宣言されていない型を Results<TResult1,TResult2,TResultN> に返そうとすると、コンパイルエラーが発生します。

要求本文とパラメーターについて記述する

OpenAPI では、エンドポイントによって返される型を記述するだけでなく、API によって使用される入力に注釈を付けることもできます。これらの入力は、2 つのカテゴリに分類されます。

パス、クエリ文字列、ヘッダー、または cookie に含まれるパラメーター
要求本文の一部として送信されるデータ

フレームワークは、ルートハンドラーのシグネチャに基づいて、パス、クエリ、ヘッダー文字列の要求パラメーターの型を自動的に推論します。

要求本文として送信される入力の型を定義するには、Accepts 拡張メソッドを使ってプロパティを構成し、要求ハンドラーで想定されるオブジェクトの種類とコンテンツタイプを定義します。次の例では、エンドポイントは要求本文で Todo オブジェクトを受け入れ、想定されるコンテンツタイプは application/xml となります。

app.MapPost("/todos/{id}", (int id, Todo todo) => ...)
  .Accepts<Todo>("application/xml");

Accepts 拡張メソッドに加えて、IEndpointParameterMetadataProvider インターフェイスを実装することで、パラメーター型がそれ自身の注釈を記述できます。たとえば、次の Todo 型は application/xml コンテンツタイプを持つ要求本文を必要とする注釈を追加します。

public class Todo : IEndpointParameterMetadataProvider
{
    public static void PopulateMetadata(ParameterInfo parameter, EndpointBuilder builder)
    {
        builder.Metadata.Add(new ConsumesAttribute(typeof(Todo), isOptional: false, "application/xml"));
    }
}

[FromForm] 属性によってフォームから読み込まれる要求本文パラメーターは、multipart/form-data コンテンツタイプで記述されます。
他のすべての要求本文パラメーターは application/json コンテンツタイプで記述されます。
要求本文が Null 許容であるか、AllowEmpty プロパティが FromBody 属性に設定されている場合は、省略可能として扱われます。

API バージョン管理のサポート

Minimal API では、Asp.Versioning.Http パッケージを使った API バージョン管理をサポートしています。 Minimal API でバージョン管理を構成する例については、API バージョン管理リポジトリを参照してください。

GitHub 上の ASP.NET Core OpenAPI ソースコード

その他のリソース

Minimal API での認証と認可

Minimal API アプリは、Swashbuckle を使用してルートハンドラーの OpenAPI 仕様を記述できます。

コントローラーベースの API での OpenAPI のサポートについては、この記事の「.NET 9 バージョン」をご覧ください。

次のコードは、OpenAPI をサポートする典型的な ASP.NET Core アプリです。

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new() { Title = builder.Environment.ApplicationName,
                               Version = "v1" });
});

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger(); // UseSwaggerUI Protected by if (env.IsDevelopment())
    app.UseSwaggerUI(c => c.SwaggerEndpoint("/swagger/v1/swagger.json",
                                    $"{builder.Environment.ApplicationName} v1"));
}

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

app.Run();

OpenAPI の記述を除外する

次のサンプルでは、OpenAPI の説明の生成から /skipme エンドポイントが除外されます。

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(); // UseSwaggerUI Protected by if (env.IsDevelopment())
}

app.MapGet("/swag", () => "Hello Swagger!");
app.MapGet("/skipme", () => "Skipping Swagger.")
                    .ExcludeFromDescription();

app.Run();

応答の種類の説明

次の例は、組み込みの結果の型を使用して応答をカスタマイズします。

app.MapGet("/api/todoitems/{id}", async (int id, TodoDb db) =>
         await db.Todos.FindAsync(id) 
         is Todo todo
         ? Results.Ok(todo) 
         : Results.NotFound())
   .Produces<Todo>(StatusCodes.Status200OK)
   .Produces(StatusCodes.Status404NotFound);

OpenAPI に操作 ID を追加する

app.MapGet("/todoitems2", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithName("GetToDoItems");

OpenAPI の記述にタグを追加する

次のコードは、OpenAPI のグループ化タグを使用します。

app.MapGet("/todoitems", async (TodoDb db) =>
    await db.Todos.ToListAsync())
    .WithTags("TodoGroup");

次の方法で共有

OpenAPI ドキュメントの操作

パッケージ インストール

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

ASP.NET Web アプリに OpenAPI メタデータを含む

要約と説明

tags

operationId

parameters

requestBody

応答の種類の説明

ProblemDetails の応答を設定する

複数応答の種類

生成されたドキュメントからのエンドポイントの除外

OpenAPI ドキュメント生成をカスタマイズするためのオプション

OpenAPI ドキュメント名をカスタマイズする

生成されたドキュメントの OpenAPI バージョンをカスタマイズする

OpenAPI エンドポイント ルートをカスタマイズする

OpenAPI エンドポイントをカスタマイズする

OpenAPI ドキュメントへのアクセスを許可されているユーザーに制限する

生成された OpenAPI ドキュメントをキャッシュする

OpenAPI ドキュメントのトランスフォーマー

トランスフォーマーを使用して OpenAPI ドキュメントをカスタマイズする

トランスフォーマーの実行順序

ドキュメント トランスフォーマーを使用する

操作トランスフォーマーを使用する

生成された OpenAPI ドキュメントの使用

ローカルのアドホック テストに Swagger UI を使用する

対話型 API ドキュメントへの Scalar の使用

生成された OpenAPI ドキュメントの Spectral によるリンティング

Microsoft.AspNetCore.OpenApi NuGet パッケージ

WithOpenApi によるエンドポイントへの OpenAPI 注釈の追加

WithOpenApi の OpenAPI 注釈を変更する

OpenAPI に操作 ID を追加する

OpenAPI の記述にタグを追加する

エンドポイントの概要または説明を追加する

OpenAPI の記述を除外する

API を古いものとしてマークする

応答の種類の説明

ProblemDetails の応答を設定する

複数応答の種類

要求本文とパラメーターについて記述する

API バージョン管理のサポート

GitHub 上の ASP.NET Core OpenAPI ソース コード

その他のリソース

OpenAPI の記述を除外する

応答の種類の説明

OpenAPI に操作 ID を追加する

OpenAPI の記述にタグを追加する

その他のリソース

パッケージインストール

`ProblemDetails` の応答を設定する

OpenAPI エンドポイントルートをカスタマイズする

ドキュメントトランスフォーマーを使用する

ローカルのアドホックテストに Swagger UI を使用する

`Microsoft.AspNetCore.OpenApi` NuGet パッケージ

`WithOpenApi` によるエンドポイントへの OpenAPI 注釈の追加

`WithOpenApi` の OpenAPI 注釈を変更する

`ProblemDetails` の応答を設定する

GitHub 上の ASP.NET Core OpenAPI ソースコード