ASP.NET Core 8 Web APIでのバージョニング実装

問題の原因

ASP.NET Core 8でWeb APIのバージョン管理を実装しようとする際、従来の.NET 6/7で使用していたMicrosoft.AspNetCore.Mvc.ApiExplorerパッケージが非推奨となりました。代わりにAsp.Versioning.Mvc.ApiExplorerパッケージを導入したところ、以下のエラーが発生します：

Unable to resolve service for type 'Asp.Versioning.ApiExplorer.IApiVersionDescriptionProvider'

これは新しいパッケージではサービス登録方法が変更されたため、依存性注入が正しく設定されていないことが原因です。

解決策：正しいサービス設定手順

1. 必要なNuGetパッケージのインストール

以下のパッケージをプロジェクトに追加します：

dotnet add package Asp.Versioning.Mvc.ApiExplorer
dotnet add package Asp.Versioning.Mvc

2. Program.csでの正しいサービス登録

サービス設定時に.AddApiExplorer()をメソッドチェーンで呼び出します：

// 正しいAPIバージョニング設定
builder.Services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
})
.AddApiExplorer(options => // メソッドチェーンで追加
{
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

3. Swagger設定の調整

Swagger設定クラスは次のように実装します：

public class ConfigureSwaggerOptions : IConfigureNamedOptions<SwaggerGenOptions>
{
    private readonly IApiVersionDescriptionProvider _provider;

    public ConfigureSwaggerOptions(IApiVersionDescriptionProvider provider)
        => _provider = provider;

    public void Configure(SwaggerGenOptions options)
    {
        foreach (var description in _provider.ApiVersionDescriptions)
        {
            options.SwaggerDoc(
                description.GroupName,
                CreateVersionInfo(description));
        }
    }

    public void Configure(string name, SwaggerGenOptions options) 
        => Configure(options);

    private static OpenApiInfo CreateVersionInfo(
        ApiVersionDescription description)
    {
        var info = new OpenApiInfo()
        {
            Title = "Your API",
            Version = description.ApiVersion.ToString(),
            Description = "API description"
        };

        if (description.IsDeprecated)
            info.Description += " (非推奨バージョン)";

        return info;
    }
}

4. Swaggerミドルウェアの登録

Program.csで設定クラスとSwaggerミドルウェアを登録：

// 設定クラスの登録
builder.Services.AddTransient<IConfigureOptions<SwaggerGenOptions>, ConfigureSwaggerOptions>();

// Swagger関連サービスの登録
builder.Services.AddSwaggerGen();

// ミドルウェアの登録（開発環境のみ）
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI(options =>
    {
        foreach (var description in app.DescribeApiVersions()
        .Select(d => d.GroupName))
        {
            options.SwaggerEndpoint(
                $"/swagger/{description}/swagger.json",
                description);
        }
    });
}

主な変更点の解説

非推奨パッケージの移行

ASP.NET Core 8ではバージョン管理システムが刷新されました：

• 旧パッケージ：Microsoft.AspNetCore.Mvc.Versioning
• 新パッケージ：Asp.Versioning.Mvc.ApiExplorer

メソッドチェーンの重要性

新しいパッケージでは.AddApiVersioning()がIApiVersioningBuilderを返します。これに対して.AddApiExplorer()を直接チェーンすることで、必要なサービスが全て登録されます。

Swagger連携の仕組み

IApiVersionDescriptionProviderサービスの実装は.AddApiExplorer()呼び出し時に自動登録されます。このため、Swagger設定クラスで依存性注入が正しく解決されるようになります。

追加設定

APIコントローラーでバージョン指定を行う例：

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class ProductsController : ControllerBase
{
    // アクションメソッド
}

よくあるエラー対処法

サービス解決エラーが続く場合

1. パッケージバージョンを確認（最新版を推奨）

   <PackageReference Include="Asp.Versioning.Mvc.ApiExplorer" Version="8.0.0" />

2. .AddApiExplorer()の呼び出し位置を確認
3. プロジェクトのビルドクリーンと再起動

注意点

AddEndpointsApiExplorer()はSwagger用の基本サービス登録ですが、APIバージョニングには.AddApiExplorer()が別途必要です。両方を併用してください：

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddApiVersioning(...).AddApiExplorer(...);

この設定により、.NET 6/7からの移行が完了し、ASP.NET Core 8の最新バージョン管理システムが正常に機能します。各APIバージョンに応じたSwaggerドキュメントも自動生成されます。