Asp.Versioningの設定
ASP.NET Coreでバージョニングを設定します。
「Asp.Versioningの設定」はCoddyKit上の無料C# Academyレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはC# Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 C# Academyコースには全4レッスンが含まれています。
Asp.Versioning パッケージ
ASP.NET Core の API バージョン管理は、コミュニティによって保守されている Asp.Versioning パッケージで提供されます（Microsoft.AspNetCore.Mvc.Versioning の後継です）。
dotnet add package Asp.Versioning.Mvc
dotnet add package Asp.Versioning.Mvc.ApiExplorerAddApiVersioning
AddApiVersioning を使ってバージョン管理を登録します。オプションでデフォルトバージョンや、バージョンがない場合の処理を制御します。
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
options.ReportApiVersions = true;
});ReportApiVersions
ReportApiVersions = true を設定すると、api-supported-versions と api-deprecated-versions のレスポンスヘッダーが追加され、クライアントが利用可能なバージョンを確認できるようになります。
// Response headers:
// api-supported-versions: 1.0, 2.0
// api-deprecated-versions: 1.0バージョンリーダーの選択
ApiVersionReader は、バージョンをどこから読み取るかを決定します。UrlSegmentApiVersionReader は、ルートパスからバージョンを読み取ります。
options.ApiVersionReader = new UrlSegmentApiVersionReader();リーダーの組み合わせ
ApiVersionReader.Combine を使うと、複数の場所から同時にバージョンを受け取れます。
options.ApiVersionReader = ApiVersionReader.Combine(
new UrlSegmentApiVersionReader(),
new HeaderApiVersionReader("X-Api-Version"),
new QueryStringApiVersionReader("api-version"));API Explorer の追加
AddApiExplorer をチェーンして、バージョニングを OpenAPI と統合します。フォーマット文字列によってバージョングループ名の形式を制御します。
builder.Services
.AddApiVersioning(options => { /* ... */ })
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});コントローラーのバージョニング
コントローラーに [ApiVersion] を付け、ルートテンプレートにバージョンのプレースホルダーを含めます。
[ApiVersion(1.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV1Controller : ControllerBase
{
[HttpGet]
public IActionResult Get() => Ok(new { version = "1.0" });
}2 番目のバージョン
別のコントローラーで、同じルートテンプレート上の v2 を提供します。{version:apiVersion} セグメントによって、リクエストが適切なコントローラーにルーティングされます。
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsV2Controller : ControllerBase
{
[HttpGet]
public IActionResult Get() =>
Ok(new { version = "2.0", extra = true });
}1 つのコントローラーで複数のバージョンを提供
1 つのコントローラーで複数のバージョンを提供し、[MapToApiVersion] を使って個々のアクションをバージョンに割り当てることができます。
[ApiVersion(1.0)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/orders")]
public class OrdersController : ControllerBase
{
[HttpGet, MapToApiVersion(1.0)]
public IActionResult GetV1() => Ok("v1");
[HttpGet, MapToApiVersion(2.0)]
public IActionResult GetV2() => Ok("v2");
}バージョンの非推奨化
バージョンを非推奨としてマークすると、機能を維持したまま廃止予定であることを知らせることができます。
[ApiVersion(1.0, Deprecated = true)]
[ApiVersion(2.0)]
[Route("api/v{version:apiVersion}/products")]
public class ProductsController : ControllerBase { }Minimal API のバージョニング
Minimal API では、NewApiVersionSet で構築したバージョンセットを使用し、その後エンドポイントごとにバージョンを関連付けます。
var versionSet = app.NewApiVersionSet()
.HasApiVersion(new ApiVersion(1, 0))
.HasApiVersion(new ApiVersion(2, 0))
.Build();
app.MapGet("/api/v{version:apiVersion}/ping", () => "pong")
.WithApiVersionSet(versionSet)
.MapToApiVersion(2.0);確認問題
AddApiExplorer の用途を確認します。
まとめ
Asp.Versioning を次のように構成しました。
AddApiVersioningで既定のバージョンとレポート機能を設定します。ApiVersionReader.Combineで URL、ヘッダー、またはクエリからバージョンを読み取ります。[ApiVersion]と{version:apiVersion}でリクエストをルーティングし、[MapToApiVersion]でアクションを対象にします。- Minimal API ではバージョンセットを使用します。
次は、OpenAPI ドキュメントの生成です。
よくある質問
「Asp.Versioningの設定」レッスンは無料ですか？
はい。「Asp.Versioningの設定」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、C# Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 C# Academyコースには全4レッスンが含まれています。
「Asp.Versioningの設定」で何を学びますか？
ASP.NET Coreでバージョニングを設定します。 ブラウザで直接実行するハンズオンコードでC# Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
C# Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのC# Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。
「Asp.Versioningの設定」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このC# Academyレッスンでコードを書いて実行できますか？
はい。すべてのC# Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- APIバージョニング戦略
- Asp.Versioningの設定
- OpenAPIドキュメントの生成
- バージョン管理されたAPIのドキュメント化