C# Academy · 课时

记录有版本的 API

Q: 「记录有版本的 API」这节课中我会学到什么？

为多个 API 版本提供文档。 你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

为多个 API 版本提供文档。

第 4 / 4 课13 个步骤

记录有版本的 API 是 CoddyKit 上的免费 C# Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 C# Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 C# Academy 课程共包含 4 节课。

每个版本一个文档

当 API 有多个版本时，通常需要为每个版本分别提供 OpenAPI 文档，这样使用者只能看到与其相关的端点。

// /openapi/v1.json -> only v1 endpoints
// /openapi/v2.json -> only v2 endpoints

API 版本描述提供程序

Asp.Versioning 提供 IApiVersionDescriptionProvider，其中列出了发现的每个 API 版本。您可以遍历它，为每个版本注册一个文档。

var provider = app.Services
    .GetRequiredService<IApiVersionDescriptionProvider>();

foreach (var desc in provider.ApiVersionDescriptions)
{
    // desc.GroupName is e.g. "v1", "v2"
}

为每个版本注册文档

每个版本组调用一次 AddOpenApi，并以该组名称命名每个文档。

builder.Services
    .AddApiVersioning()
    .AddApiExplorer(o =>
    {
        o.GroupNameFormat = "'v'VVV";
        o.SubstituteApiVersionInUrl = true;
    });

builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");

将端点筛选到正确的文档中

使用文档转换器或 ShouldInclude 谓词，让每个文档只包含属于其版本的端点，并通过组名称进行匹配。

builder.Services.AddOpenApi("v1", options =>
{
    options.ShouldInclude = description =>
        description.GroupName == "v1";
});

映射文档

使用默认模式的 MapOpenApi 会在 /openapi/{documentName}.json 提供每个命名文档。

app.MapOpenApi();
// /openapi/v1.json and /openapi/v2.json both available

设置每个文档的信息

在转换器中为每个版本文档设置独立的标题和版本，使文档能够自我说明。

builder.Services.AddOpenApi("v2", options =>
{
    options.AddDocumentTransformer((doc, ctx, ct) =>
    {
        doc.Info.Title = "Catalog API v2";
        doc.Info.Version = "2.0";
        return Task.CompletedTask;
    });
});

在文档中标记已弃用的版本

如果某个版本已弃用，请在其文档描述中显示这一点，以便使用者在用户界面中看到警告。

options.AddDocumentTransformer((doc, ctx, ct) =>
{
    if (ctx.DocumentName == "v1")
        doc.Info.Description = "DEPRECATED - migrate to v2.";
    return Task.CompletedTask;
});

替换 URL 中的版本

SubstituteApiVersionInUrl = true 会将文档中的 {version:apiVersion} 路由令牌改写为具体版本（例如 v1），使路径更加清晰。

// Without: /api/v{version}/products
// With:    /api/v1/products

每个版本一个用户界面标签页

大多数查看器都可以显示包含所有文档的下拉列表。配置用户界面，使其指向每个版本的 JSON 文档。

app.MapScalarApiReference(options =>
{
    options.AddDocument("v1", "API v1", "/openapi/v1.json");
    options.AddDocument("v2", "API v2", "/openapi/v2.json");
});

记录请求和响应的数据结构

由于 v2 可能会更改 DTO，请为每个版本提供独立的 DTO 类型。OpenAPI 随后会自动为每个文档呈现不同的架构。

// V1 DTO
public record ProductV1(int Id, string Name);
// V2 DTO (breaking change)
public record ProductV2(int Id, string Title, decimal Price);

整合起来

完整流程是：配置版本控制和 API 浏览器，为每个版本注册一个带筛选器的 OpenApi 文档，将这些文档映射出来，然后让用户界面指向每个文档。

builder.Services.AddApiVersioning().AddApiExplorer(o =>
{
    o.GroupNameFormat = "'v'VVV";
    o.SubstituteApiVersionInUrl = true;
});
builder.Services.AddOpenApi("v1");
builder.Services.AddOpenApi("v2");
// ...
app.MapOpenApi();
app.MapScalarApiReference();

快速检查

请确认版本化文档的生成方式。

在交互式课程中回答

回顾

您记录了版本化 API 的文档：

使用 AddOpenApi("vN") 为每个版本注册一个命名的 OpenAPI 文档。
IApiVersionDescriptionProvider 枚举版本；ShouldInclude 筛选端点。
SubstituteApiVersionInUrl 呈现包含具体版本的路由。
让用户界面指向每个文档，以提供每个版本的独立视图。

版本控制和 OpenAPI 课程到此完成。

免费开始

用 AI 导师学习 C# — 免费

在浏览器中编写并运行真实代码，获得全天候 AI 导师的即时帮助，并在网页或应用中继续学习。

课程: 93
课程: 346

免费开始学习查看完整课程

常见问题解答

「记录有版本的 API」课时是免费的吗？

是的 — 「记录有版本的 API」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 C# Academy 课程的其余内容，请升级到 CoddyKit PRO。 C# Academy 课程共包含 4 节课。

「记录有版本的 API」这节课中我会学到什么？

为多个 API 版本提供文档。你通过在浏览器中直接运行的动手代码来练习 C# Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 C# Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 C# Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「记录有版本的 API」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 C# Academy 课中编写并运行代码吗？

能。每节 C# Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 C# Academy