.NET 10におけるAPIバージョニングとOpenAPIの統合：Asp.Versioning v10による効率的な実装（2026年4月版）

2026年5月1日

API開発

近年、ASP.NET Coreを用いたAPI開発は劇的な進化を遂げました。

Minimal APIの導入やコントローラーベースの設計手法が洗練されたことで、スケーラブルなアプリケーションを構築するハードルはかつてないほど下がっています。

特に最新の .NET 10では、Minimal APIにおけるリクエストバリデーションの組み込みサポートなど、開発効率を向上させる強力な機能が追加されました。

しかし、APIが成長し、多くのクライアントに利用されるようになると、避けては通れない課題が浮上します。

それが「APIバージョニング」です。

本記事では、2026年4月にリリースされた最新の情報を基に、.NET 10におけるAPIバージョニングとOpenAPIの統合手法について解説します。

目次 [ close ]

APIバージョニングの重要性と主要な戦略

APIバージョニングは、既存のクライアントに影響を与えることなく、APIを継続的に進化させるために不可欠な要素です。

新機能の追加や破壊的な変更を行う際、バージョニングが適切に運用されていれば、後方互換性を維持しながらスムーズな移行を促すことができます。

一般的にASP.NET Coreで採用されるバージョニング戦略には、主に以下の4つのアプローチがあります。

URLパスによるバージョニング (例: /api/v1/resource)：最も一般的で、どのバージョンを呼び出しているかが明確です。
クエリ文字列によるバージョニング (例: /api/resource?api-version=1.0)：URLの構造を維持したまま、パラメーターで制御します。
ヘッダーによるバージョニング (例: X-API-Version: 1.0)：リソースのURLを純粋に保つことができ、RESTfulな設計に適しています。
メディアタイプによるバージョニング (例: Accept: application/json; v=1.0)：コンテンツ交渉を利用する高度な手法です。

これらの戦略を独自に実装することも可能ですが、.NETエコシステムではAsp.Versioningというライブラリを使用するのが標準的な選択肢です。

特に2026年4月にリリースされたAsp.Versioning v10.0.0は、.NET 10と新しいOpenAPIサポートを公式に統合した最初のバージョンであり、これまでの複雑な設定を大幅に簡略化しています。

.NET 9および.NET 10におけるOpenAPIの変化

.NET 9以降、Microsoftは従来の Swashbuckle.AspNetCore に代わる標準機能として、Microsoft.AspNetCore.OpenApi パッケージを導入しました。

これにより、外部ライブラリに依存せず、ASP.NET Coreのランタイムと密接に連携したOpenAPIドキュメントの生成が可能になっています。

デフォルトの状態では、OpenAPIドキュメントは /openapi/v1.json というURLで提供されます。

これは一見するとバージョニングに対応しているように見えますが、実際にはASP.NET Core自体に高度なAPIバージョニング機能が組み込まれているわけではありません。

そのため、複数のバージョンを管理しようとすると、ドキュメントの定義が重複したり、手動での設定が必要になったりするという課題がありました。

Asp.Versioning v10 は、この新しい標準OpenAPIライブラリとシームレスに連携するように設計されており、わずかなコード変更でバージョンごとのドキュメントを自動生成できるようになっています。

Asp.VersioningによるAPIバージョニングの実装

まずは、OpenAPIとの統合を考える前に、基本的なAPIバージョニングのセットアップ方法を確認しましょう。

.NET 10では、C# 14のファイルベースアプリ (file-based apps)機能により、単一のファイルでアプリケーションを記述できるようになりました。

コントローラーでのバージョニング

コントローラーベースのAPIでは、Asp.Versioning.Mvc パッケージを使用します。

#:property PublishAot=false
#:sdk Microsoft.NET.Sdk.Web
#:package Asp.Versioning.Mvc@10.0.0

using Asp.Versioning;
using Microsoft.AspNetCore.Mvc;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// APIバージョニングのサービスを登録
builder.Services.AddApiVersioning()
    .AddMvc();

var app = builder.Build();

app.MapControllers();
app.Run();

[ApiController]
[Route("api/users")]
[ApiVersion("1.0")]
public class UsersV1Controller : ControllerBase
{
    [HttpGet]
    public ActionResult Get() => Ok(new[] { new { Id = 1, Name = "John Doe" } });
}

[ApiController]
[Route("api/users")]
[ApiVersion("2.0")]
public class UsersV2Controller : ControllerBase
{
    [HttpGet]
    public ActionResult Get() => Ok(new[] { new { Id = 1, Name = "John Doe", BirthDate = new DateOnly(1990, 1, 1) } });
}

この設定により、クライアントは api/users?api-version=1.0 のようにクエリ文字列を指定してアクセスできるようになります。

Minimal APIでのバージョニング

Minimal APIの場合は、Asp.Versioning.Http を使用します。

using Asp.Versioning;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddApiVersioning();
var app = builder.Build();

// バージョン管理されたAPIグループの作成
var usersApi = app.NewVersionedApi("Users");

var v1 = usersApi.MapGroup("api/users").HasApiVersion("1.0");
var v2 = usersApi.MapGroup("api/users").HasApiVersion("2.0");

v1.MapGet("", () => Results.Ok(new[] { new { Id = 1, Name = "John Doe" } }));
v2.MapGet("", () => Results.Ok(new[] { new { Id = 1, Name = "John Doe", BirthDate = "1990-01-01" } }));

app.Run();

OpenAPIとバージョニングの統合

.NET 10と Asp.Versioning v10 を組み合わせる最大のメリットは、バージョンごとに独立したOpenAPIドキュメントを最小限の設定で生成できる点にあります。

これには、新しく導入された Asp.Versioning.OpenApi パッケージが必要です。

統合のステップ

以下のコードは、Minimal APIでの統合例です。

#:package Asp.Versioning.Http@10.0.0
#:package Asp.Versioning.Mvc.ApiExplorer@10.0.0
#:package Asp.Versioning.OpenApi@10.0.0

using Asp.Versioning;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddApiVersioning()
    .AddApiExplorer(options =>
    {
        // APIドキュメントのグループ化フォーマットを指定 ('v1', 'v2' など)
        options.GroupNameFormat = "'v'VVV";
    })
    .AddOpenApi(); // Asp.Versioningの拡張メソッドを呼び出す

var app = builder.Build();

// バージョンごとのエンドポイントを自動生成
app.MapOpenApi().WithDocumentPerVersion();

// APIの定義...
var usersApi = app.NewVersionedApi("Users");
usersApi.MapGroup("api/users").HasApiVersion("1.0").MapGet("", () => "v1");
usersApi.MapGroup("api/users").HasApiVersion("2.0").MapGet("", () => "v2");

app.Run();

この実装における重要なポイントは、WithDocumentPerVersion() です。

これにより、開発者は個別に AddOpenApi("v1")、AddOpenApi("v2") といった設定を記述する必要がなくなります。

Asp.Versioningがエンドポイントの定義を読み取り、/openapi/v1.json や /openapi/v2.json を自動的に構成します。

UIツールによる可視化：Swagger UIとScalar

生成されたOpenAPIドキュメントを人間が読みやすい形式で表示するために、Swagger UI や Scalar を導入しましょう。

Swagger UIのセットアップ

.NET 9/10ではSwagger UIが標準ではなくなりましたが、Swashbuckle.AspNetCore.SwaggerUI パッケージのみを利用して、UI機能だけを追加できます。

app.UseSwaggerUI(options =>
{
    // 登録されているすべてのバージョンをループしてエンドポイントを追加
    foreach (var description in app.DescribeApiVersions().Reverse())
    {
        options.SwaggerEndpoint(
            $"/openapi/{description.GroupName}.json",
            description.GroupName.ToUpperInvariant());
    }
});

ScalarによるモダンなUI

最新のトレンドとして注目されているのが Scalar です。

非常に高速で、デフォルトでダークモードや優れたコード生成機能を備えています。

app.MapScalarApiReference(options =>
{
    var descriptions = app.DescribeApiVersions();
    for (var i = 0; i < descriptions.Count; i++)
    {
        var description = descriptions[i];
        var isDefault = i == descriptions.Count - 1;
        options.AddDocument(description.GroupName, description.GroupName, isDefault: isDefault);
    }
});

これにより、/scalar にアクセスするだけで、バージョンを切り替えながらAPIを試せる洗練されたインターフェースを利用可能になります。

v8からv10への移行と改善点

従来の Asp.Versioning v8 では、.NET 9/10の新しいOpenAPIライブラリと連携させるために、多くのカスタムトランスフォーマーや複雑な設定が必要でした。

しかし、v10.0.0 では以下の点が大きく改善されています。

改善項目	v8 (以前の対応)	v10 (.NET 10対応)
OpenAPI登録	バージョンごとに `AddOpenApi()` が必要	`AddOpenApi()` 1回で全バージョン対応
エンドポイント生成	手動でのマッピングが必要	`WithDocumentPerVersion()` で自動化
依存関係	互換性維持のための回避策が必要	公式に組み込みOpenAPIをサポート

この進化により、コードの重複が劇的に減少し、新しいバージョンを追加する際のメンテナンスコストが大幅に削減されました。

APIリンティングによる品質管理

バージョニングを導入してAPIを公開した後は、その品質を維持することが重要です。

特に複数のバージョンが存在する場合、設計の整合性が失われやすくなります。

そこで活用したいのが APIリンティング です。

Spectral：OpenAPI定義が組織のルールに従っているかを自動チェックします。
oasdiff：バージョン間の差異を検出し、意図しない破壊的変更が加えられていないかを監視します。

これらのツールをCI/CDパイプラインに組み込むことで、「新しいバージョンを定義すべきなのに、既存のバージョンに破壊的変更を加えてしまった」というミスを未然に防ぐことができます。

まとめ

.NET 10と Asp.Versioning v10 の組み合わせは、APIバージョニングの実装における新しいスタンダードを確立しました。

従来の複雑な設定は過去のものとなり、AddOpenApi() や WithDocumentPerVersion() といった直感的なメソッドを通じて、強力なドキュメント管理機能を手に入れることができます。

APIは一度公開すれば、それを使い続けるクライアントが存在します。

適切なバージョニング戦略とOpenAPIの統合は、開発者にとっても利用者にとっても長期的な利益をもたらします。

Swagger UIやScalarといったツールを活用して可視性を高め、Spectralなどのリンターで品質を担保しながら、安全にAPIを進化させていきましょう。

2026年のモダンな開発環境において、この統合手法はプロジェクトの成功を支える重要な鍵となります。