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

[アーティクル]
11/06/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 ドキュメント生成を構成する

コード例を次に示します。

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
.NET CLI

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

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

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

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

インストール時に、このパッケージはビルド時にアプリケーションに関連付けられている 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();
}

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
    });

応答の種類の説明

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 を使用して、エンドポイントのメタデータに適切な注釈を追加できます。 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 ドキュメント生成を構成する

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

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

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

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

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

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

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

ビルド時に OpenAPI ドキュメントを生成する

ビルド時のドキュメント生成のカスタマイズ

生成された Open API ファイルの出力ディレクトリの変更

出力ファイル名の変更

生成する OpenAPI ドキュメントの選択

ビルド時ドキュメントの生成中の実行時動作のカスタマイズ

Microsoft.AspNetCore.OpenApi NuGet パッケージ

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

WithOpenApi の OpenAPI 注釈を変更する

OpenAPI に操作 ID を追加する

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

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

OpenAPI の記述を除外する

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

応答の種類の説明

ProblemDetails の応答を設定する

複数応答の種類

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

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

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

その他のリソース

OpenAPI の記述を除外する

応答の種類の説明

OpenAPI に操作 ID を追加する

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

その他のリソース

パッケージインストール

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

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

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

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

`ProblemDetails` の応答を設定する

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