dotnet-openapi

dotnet-openapi

ASP.NET Core 向けの OpenAPI／Swagger 統合です。Microsoft.AspNetCore.OpenApi は .NET 9 以降で推奨されるファーストパーティの方法であり、新しいプロジェクトテンプレートの既定になっています。Swashbuckle は現在、積極的にメンテナンスされていません。Swashbuckle を使用している既存のプロジェクトでは、移行を計画してください。NSwag は、クライアント生成や高度なシナリオ向けの代替手段です。

対象外： Minimal API のエンドポイントパターン（ルートグループ、フィルター、TypedResults）については、[skill:dotnet-minimal-apis] を参照してください。API のバージョニング戦略については、[skill:dotnet-api-versioning] を参照してください。認証と認可については、[skill:dotnet-api-security] を参照してください。

相互参照：OpenAPI メタデータを生成するエンドポイントパターンについては [skill:dotnet-minimal-apis] を、バージョン付き OpenAPI ドキュメントについては [skill:dotnet-api-versioning] を参照してください。

---

Microsoft.AspNetCore.OpenApi（推奨）

Microsoft.AspNetCore.OpenApi は、ASP.NET Core 9 以降向けのファーストパーティ OpenAPI パッケージで、新しいプロジェクトテンプレートに既定で含まれています。.NET 10 では、JSON Schema draft 2020-12 に準拠した OpenAPI 3.1 のサポートが追加されます。

基本的なセットアップ

// Microsoft.AspNetCore.OpenApi -- included by default in .NET 9+ project templates
// If not present, add: <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="9.*" />
// Version must match the project's target framework major version

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // Serves /openapi/v1.json
}

複数のドキュメント

API のバージョンまたは機能グループごとに、個別の OpenAPI ドキュメントを生成します。

builder.Services.AddOpenApi("v1", options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_0;
});

builder.Services.AddOpenApi("v2", options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
});

var app = builder.Build();
app.MapOpenApi(); // Serves /openapi/v1.json and /openapi/v2.json

---

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

ドキュメントトランスフォーマーは、生成された OpenAPI ドキュメントの構築後に変更を加えます。サーバー情報、セキュリティスキーム、カスタムメタデータの追加に使用します。

IOpenApiDocumentTransformer

public sealed class SecuritySchemeTransformer : IOpenApiDocumentTransformer
{
    public Task TransformAsync(
        OpenApiDocument document,
        OpenApiDocumentTransformerContext context,
        CancellationToken cancellationToken)
    {
        document.Components ??= new OpenApiComponents();
        document.Components.SecuritySchemes["Bearer"] = new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.Http,
            Scheme = "bearer",
            BearerFormat = "JWT",
            Description = "JWT Bearer token authentication"
        };

        document.SecurityRequirements.Add(new OpenApiSecurityRequirement
        {
            [new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            }] = Array.Empty<string>()
        });

        return Task.CompletedTask;
    }
}

// Register the transformer
builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer<SecuritySchemeTransformer>();
});

ラムダ式によるドキュメントトランスフォーマー

シンプルな変換には、ラムダ式のオーバーロードを使用します。

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, ct) =>
    {
        document.Info = new OpenApiInfo
        {
            Title = "Products API",
            Version = "v1",
            Description = "Product catalog management API",
            Contact = new OpenApiContact
            {
                Name = "API Support",
                Email = "[email protected]"
            }
        };
        return Task.CompletedTask;
    });
});

---

オペレーショントランスフォーマー

オペレーショントランスフォーマーは、OpenAPI ドキュメント内の個々の操作（エンドポイント）を変更します。操作ごとのメタデータ、例、条件付きロジックの追加に使用します。

public sealed class DeprecationTransformer : IOpenApiOperationTransformer
{
    public Task TransformAsync(
        OpenApiOperation operation,
        OpenApiOperationTransformerContext context,
        CancellationToken cancellationToken)
    {
        var deprecatedAttr = context.Description.ActionDescriptor
            .EndpointMetadata
            .OfType<ObsoleteAttribute>()
            .FirstOrDefault();

        if (deprecatedAttr is not null)
        {
            operation.Deprecated = true;
            operation.Description = $"DEPRECATED: {deprecatedAttr.Message}";
        }

        return Task.CompletedTask;
    }
}

builder.Services.AddOpenApi(options =>
{
    options.AddOperationTransformer<DeprecationTransformer>();
});

---

スキーマのカスタマイズ

スキーマトランスフォーマーを使用して、.NET 型を OpenAPI スキーマにマッピングする方法をカスタマイズします。

builder.Services.AddOpenApi(options =>
{
    options.AddSchemaTransformer((schema, context, ct) =>
    {
        // Add example values for known types
        if (context.JsonTypeInfo.Type == typeof(ProductDto))
        {
            schema.Example = new OpenApiObject
            {
                ["id"] = new OpenApiInteger(1),
                ["name"] = new OpenApiString("Widget"),
                ["price"] = new OpenApiDouble(19.99)
            };
        }
        return Task.CompletedTask;
    });
});

エンドポイントメタデータの拡充

エンドポイントビルダーの流れるようなメソッドを使用して、OpenAPI メタデータを充実させます。

products.MapGet("/{id:int}", GetProductById)
    .WithName("GetProductById")
    .WithSummary("Get a product by its ID")
    .WithDescription("Returns the product details for the specified ID, or 404 if not found.")
    .WithTags("Products")
    .Produces<Product>(StatusCodes.Status200OK)
    .ProducesProblem(StatusCodes.Status404NotFound);

---

Swashbuckle からの移行

Swashbuckle（Swashbuckle.AspNetCore）は現在、積極的にメンテナンスされていません。OpenAPI 3.1 はサポートしていません。既存のプロジェクトでは、Microsoft.AspNetCore.OpenApi への移行を計画してください。

Swashbuckle を引き続き使用する必要がある場合： .NET 9 以降にアップグレードできない .NET 8 のプロジェクトや、Swashbuckle 固有の機能（詳細なカスタマイズが可能な SwaggerUI、ISchemaFilter パイプライン）に依存するプロジェクトでは、移行を計画しながら Swashbuckle を引き続き使用できます。

移行手順

1. Swashbuckle パッケージを削除します。

2. サービス登録を置き換えます。

// Before (Swashbuckle)
builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
});

// After (Microsoft.AspNetCore.OpenApi)
builder.Services.AddOpenApi();

3. ミドルウェアを置き換えます。

// Before (Swashbuckle)
app.UseSwagger();
app.UseSwaggerUI();

// After (built-in)
app.MapOpenApi(); // Serves raw OpenAPI JSON at /openapi/v1.json

4. Swagger UI には、スタンドアロンの UI パッケージを追加するか、Scalar を使用します。

// Option 1: Scalar (modern, built-in support in .NET 10)
// <PackageReference Include="Aspire.Dashboard.Components.Scalar" ... /> or use MapScalarApiReference
app.MapScalarApiReference(); // .NET 10

// Option 2: Swagger UI standalone
// <PackageReference Include="Swashbuckle.AspNetCore.SwaggerUI" Version="..." />
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/openapi/v1.json", "v1");
});

5. Swashbuckle のフィルターをトランスフォーマーに移行します。

Swashbuckle の概念	組み込みの代替手段
IDocumentFilter	IOpenApiDocumentTransformer
IOperationFilter	IOpenApiOperationTransformer
ISchemaFilter	AddSchemaTransformer によるスキーマトランスフォーマー
[SwaggerOperation]	.WithSummary()、.WithDescription()
[SwaggerResponse]	.Produces<T>()、TypedResults

---

NSwag

NSwag は、ドキュメント生成、クライアント生成（C#、TypeScript）、UI を備えた OpenAPI ツールチェーンの代替手段です。生成された API クライアントが必要な場合や、.NET 以外のコンシューマーと連携する場合に役立ちます。

ドキュメント生成

// <PackageReference Include="NSwag.AspNetCore" Version="14.*" />
builder.Services.AddOpenApiDocument(options =>
{
    options.Title = "Products API";
    options.Version = "v1";
    options.DocumentName = "v1";
});

var app = builder.Build();
app.UseOpenApi();    // Serves /swagger/v1/swagger.json
app.UseSwaggerUi(); // Serves /swagger UI

クライアント生成

NSwag は、OpenAPI 仕様から型付きの C# または TypeScript クライアントを生成します。

# Install NSwag CLI
dotnet tool install --global NSwag.ConsoleCore

# Generate C# client from OpenAPI spec
nswag openapi2csclient /input:https://api.example.com/openapi/v1.json \
    /output:GeneratedClient.cs \
    /namespace:MyApp.ApiClient \
    /generateClientInterfaces:true

推奨事項： ドキュメント生成には Microsoft.AspNetCore.OpenApi を使用してください。生成された OpenAPI 仕様からのクライアント生成には、NSwag CLI または Kiota を使用してください。新しいプロジェクトでは、生成と提供の両方に NSwag を使用することは避けてください。

---

OpenAPI 3.1（.NET 10）

.NET 10 では、JSON Schema draft 2020-12 への準拠とともに、OpenAPI 3.1 が完全にサポートされます。3.0 からの主な改善点は次のとおりです。

• Nullable 型： nullable: true ではなく、JSON Schema の type: ["string", "null"] を使用します
• Discriminator の改善： 多相型に対する oneOf／anyOf のサポートが強化されています
• Webhooks： Webhook 定義を標準でサポートします
• JSON Schema との整合性： JSON Schema draft 2020-12 のツールとの完全な互換性があります

// .NET 10: OpenAPI 3.1 is the default
// <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.*" />
builder.Services.AddOpenApi(options =>
{
    // Explicitly set version if needed (3.1 is default in .NET 10)
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
});

注意点： Swashbuckle は OpenAPI 3.1 をサポートしていません。3.1 の機能が必要なプロジェクトでは、Microsoft.AspNetCore.OpenApi への移行が必要です。

---

エージェント利用時の注意点

1. バージョンが一致しない Microsoft.AspNetCore.OpenApi のメジャーバージョンを固定しないでください -- パッケージのバージョンは、プロジェクトのターゲットフレームワークのメジャーバージョンと一致している必要があります。互換性のない OpenAPI スタック（例：Swashbuckle と組み込み機能）を同じプロジェクトで混在させないでください。
2. 新しい .NET 9 以降のプロジェクトに Swashbuckle を推奨しないでください -- 現在は積極的にメンテナンスされていません。代わりに、組み込みの Microsoft.AspNetCore.OpenApi を使用してください。
3. Swashbuckle を「非推奨」と言わないでください -- 正式に非推奨になったわけではありませんが、現在は積極的にメンテナンスされていません。組み込みの代替機能について言及する場合は、「望ましい」または「推奨」としてください。
4. Swagger UI の代替手段を忘れないでください -- MapOpenApi() が提供するのは未加工の JSON 仕様のみです。Scalar、Swagger UI standalone、または別の UI を個別に追加してください。
5. Swashbuckle と組み込みの OpenAPI を同じプロジェクトで混在させないでください -- 競合するドキュメントが生成されます。どちらか一方を選択してください。
6. ASP.NET 共有フレームワークのパッケージバージョンをハードコードしないでください -- Microsoft.AspNetCore.OpenApi などのパッケージは、プロジェクトの TFM のメジャーバージョンと一致している必要があります。

---

前提条件

• Microsoft.AspNetCore.OpenApi には .NET 9.0 以降が必要です（既定のプロジェクトテンプレートに含まれています）
• OpenAPI 3.1、JSON Schema draft 2020-12、および Scalar の統合には .NET 10.0 が必要です
• NSwag ベースの生成と UI には NSwag.AspNetCore（オプション）
• まだ移行していない既存のプロジェクトには Swashbuckle.AspNetCore（レガシー）

---

参考資料

• ASP.NET Core の OpenAPI
• Microsoft.AspNetCore.OpenApi
• OpenAPI ドキュメントトランスフォーマー
• Swashbuckle からの移行
• NSwag
• Scalar API リファレンス