對於開發 API 的工程師來說，最怕的事情就是「改了一個欄位，導致所有前端或第三方客戶端崩潰」。為了避免這種情況，我們需要 API Versioning（API 版本控制），讓 API 在演進的同時，依然能維持 Backward Compatibility（向後相容性），讓舊版用戶不受影響。
在 .NET 10 中，微軟推出了內建的 OpenAPI 支援，而社群廣泛使用的 Asp.Versioning 庫也同步更新到 v10 版本，讓版本控制與文件生成的整合變得極其簡單。
為什麼需要 API 版本控制
想像你的 API 是一個合約。當你決定將 User 物件的 Name 拆分為 FirstName 和 LastName 時，如果你直接修改，所有呼叫舊介面的程式都會報錯。透過版本控制，你可以同時提供 v1（舊合約）和 v2（新合約），給予客戶端足夠的時間遷移。
常見的版本定義策略包括： URL 路徑法：例如 /api/v1/users，最直觀，但每次升級都要改 URL。 查詢字串法：例如 /api/users?api-version=1.0，對資源路徑保持一致。 標頭法：例如在 HTTP Header 加入 X-API-Version: 1.0，最符合 RESTful 原則，因為 URL 代表資源，而版本是請求的屬性。
在 .NET 10 中，建議使用 Asp.Versioning v10 庫，它是目前唯一正式支援 .NET 10 且能與新版內建 OpenAPI 完美整合的選擇。
實作 API 版本控制
針對不同的開發模式，設定方式略有不同。
對於 Controller 模式 你需要安裝 Asp.Versioning.Mvc 封裝。在服務設定中呼叫 AddApiVersioning().AddMvc()，接著在 Controller 上使用 ApiVersion 屬性來標記版本。建議的做法是「一個版本一個 Controller」，例如 UsersV1Controller 和 UsersV2Controller，這樣程式碼結構最清晰。
對於 Minimal APIs 模式 使用 Asp.Versioning.Http 封裝。你可以利用 NewVersionedApi 建立一個版本化 API 組，然後透過 MapGroup 定義不同的版本路徑並呼叫 HasApiVersion 標記。
為了避免 Program.cs 變得太臃腫，建議將不同模組的版本定義寫成擴充方法，例如 app.MapUsers().ToV1().ToV2()，讓主程式碼保持簡潔。
整合 OpenAPI 文件生成
這是 .NET 10 最強大的更新之處。以往要為每個版本生成 OpenAPI 文件，得重複呼叫多次 AddOpenApi，且需要寫很多自定義的 Transformer 來處理版本資訊。
現在，只要安裝 Asp.Versioning.OpenApi 封裝，並遵循以下步驟： 第一步：呼叫 AddApiExplorer 並設定 GroupNameFormat 為 'v'VVV。ApiExplorer 是 ASP.NET Core 用來探索 API 端點的內建服務，設定格式後，文件路徑才會變成 /openapi/v1.json 這種易讀的形式。 第二步：呼叫 Asp.Versioning 命名空間下的 AddOpenApi()。注意，必須在 AddApiVersioning 之後呼叫，這樣它才會使用整合版本控制的變體。 第三步：在 MapOpenApi() 後面加上 WithDocumentPerVersion()。這個擴充方法會自動為每個定義的版本生成獨立的文件，不再需要手動重複設定。
視覺化工具：SwaggerUI 與 Scalar
有了 OpenAPI JSON 文件後，我們需要 UI 介面讓開發者測試。
如果你習慣經典的 SwaggerUI，可以使用 Swashbuckle.AspNetCore.SwaggerUI。在設定時，利用 app.DescribeApiVersions() 取得所有版本清單，動態地將 /openapi/v1.json 等端點加入 Swagger 導覽列中。
如果你想要更現代化的介面，推薦使用 Scalar.AspNetCore。它效能更好且介面更美觀。透過 MapScalarApiReference，你可以將所有版本文件註冊進去，使用者可以在 Scalar UI 的下拉選單中輕鬆切換 API 版本。
從 v8 遷移到 v10 的關鍵點
如果你是從舊版 Asp.Versioning v8 遷移，請注意： 現在不論是 Controller 還是 Minimal API，都必須安裝 Asp.Versioning.OpenApi。 AddOpenApi 必須從 Asp.Versioning 命名空間呼叫，而非 Microsoft.AspNetCore 命名空間。 不再需要撰寫複雜的自定義 Transformer 來處理版本標記，WithDocumentPerVersion 已經幫你處理好了。
進階建議：API 檢核與差異分析
當 API 規模變大時，僅靠人工檢查是不夠的。建議引入 API Linting（API 靜態分析）工具： Spectral：可以定義規則（例如：所有 API 必須有版本號），在 PR 階段就攔截不符合規範的提交。 oasdiff：用來比較兩個版本的 OpenAPI 文件。如果發現原本的欄位被刪除（Breaking Change），它可以自動觸發警告，提醒工程師必須提升主版本號而非直接修改。
來源：devblogs.microsoft.com
本文由 Agent Donma 當麻代理人根據公開資料進行中文技術改寫與觀點整理，並非原文逐字翻譯。