使用 OpenAPI 3.2 的 itemSchema 描述 Server-Sent Events 响应:practical-aspnetcore 中 open-api-13 实战解析
使用 OpenAPI 3.2 的 itemSchema 描述 Server-Sent Events 响应:practical-aspnetcore 中 open-api-13 实战解析
在 ASP.NET Core 11 中,text/event-stream(Server-Sent Events,SSE)响应终于可以在生成的 OpenAPI 文档中被精确描述:OpenAPI 3.2 引入了 itemSchema,它专门用于声明流式响应中"每一个事件载荷"的类型,而不再让 SSE 端点停留在"无响应体描述"的状态。本篇文章以 practical-aspnetcore 仓库中的 projects/net11/open-api-13 示例为骨架,完整讲解如何利用 .NET 11 默认生成的 OpenAPI 3.2 文档,配合 TypedResults.ServerSentEvents 与 SseItem<T>,让 SSE 端点的逐事件数据类型被 itemSchema 正确建模。读完本文,你将掌握:SSE 响应在 OpenAPI 3.2 中的标准描述方式、SseItem<T> 的类型化用法、如何验证生成的文档内容,以及一个容易踩坑的返回值陷阱。
OpenAPI 3.2 的 itemSchema:SSE 响应描述的核心机制
长期以来,OpenAPI 规范对 SSE 这类"流式、多事件、事件间类型不同"的响应缺乏标准描述手段。HTTP 响应头 Content-Type: text/event-stream 表明响应体是一个事件流,但规范层面上并没有一个字段可以说明"流中的每一条事件携带什么类型的数据"。
OpenAPI 3.2 解决了这个问题:规范新增了 itemSchema,它允许将流式响应(典型如 SSE)的响应体声明为一个元素列表,并通过 itemSchema 描述其中单个元素(即单个事件载荷)的类型。正如 open-api-13 的 README 所言:
OpenAPI 3.2 added
itemSchemasupport sotext/event-streamresponses describe the per-event payload type.
这意味着:当你的最小 API 返回一个 IAsyncEnumerable<SseItem<Todo>> 事件流时,OpenAPI 文档中该响应的 content['text/event-stream'].schema 会携带 itemSchema 字段,并指向类型 Todo 在 components/schemas 中的定义,从而让 API 消费者(无论是人还是代码生成器)都能知道:每条 SSE 事件的 data 都是一个 Todo 对象。
示例全景:一个微型 Todo SSE 端点
open-api-13 是一个完整的微型可运行项目,目录结构如下:
- projects/net11/open-api-13/Program.cs —— 全部逻辑:OpenAPI 注册、SSE 端点、数据源
- projects/net11/open-api-13/open-api-13.csproj —— 项目文件,声明 .NET 11 目标框架与 OpenAPI 包
- projects/net11/open-api-13/README.md —— 示例说明
项目文件(open-api-13.csproj)的要点如下:
<Project Sdk="Microsoft.NET.Sdk.Web">
<PropertyGroup>
<TargetFramework>net11.0</TargetFramework>
<ImplicitUsings>true</ImplicitUsings>
<LangVersion>preview</LangVersion>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="11.0.0-preview.7.26381.103" />
</ItemGroup>
</Project>
关键信息:
- 目标框架为
net11.0,与仓库根目录 global.json 中声明的 SDK11.0.100-rc.1.26425.128(rollForward 为 major)对应,属于 .NET 11 的预览/RC 阶段版本; - 通过
Microsoft.AspNetCore.OpenApi包获得AddOpenApi()/MapOpenApi()能力; LangVersion为preview,用于启用预览语法特性(示例中使用了集合表达式[...]等新语法)。
运行方式与仓库其他示例一致:
dotnet run
启动后访问首页,页面会提供两个链接:/openapi/v1.json(查看生成的 OpenAPI 文档)和 /todos/stream(实际的 SSE 端点)。
核心代码逐段拆解
1. 默认即 OpenAPI 3.2:无需显式配置版本
在 .NET 11 中,OpenAPI 3.2 已成为 AddOpenApi() 的默认生成版本。对比仓库中另一个示例 projects/net11/open-api-12/Program.cs 可以看到差异:
// open-api-12:需要显式指定版本
builder.Services.AddOpenApi(options =>
{
options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_2;
});
而 open-api-13 则完全没有版本配置:
// OpenAPI 3.2 is the default generated version in .NET 11
builder.Services.AddOpenApi();
var app = builder.Build();
app.MapOpenApi();
从源码结构看,AddOpenApi() 在不传任何选项时即产出 3.2 版本文档,MapOpenApi() 则把文档挂载到默认路由 /openapi/v1.json。因此本项目无需任何显式配置即可验证 "openapi: 3.2.0" 的文档版本字段。
2. 首页端点:ExcludeFromDescription 排除非 API 端点
app.MapGet("/", () => Results.Text("""
<html><body>
<h1>OpenAPI 3.2 + Server-Sent Events itemSchema</h1>
<ul>
<li><a href="/openapi/v1.json">OpenAPI document</a></li>
<li><a href="/todos/stream">GET /todos/stream</a> a text/event-stream endpoint</li>
</ul>
</body></html>
""", "text/html")).ExcludeFromDescription();
首页返回一段 HTML 导航页,并通过 .ExcludeFromDescription() 将其从 OpenAPI 文档中排除——这是一个纯 UI 辅助页面,并非 API 端点。这一做法在仓库的 OpenAPI 系列示例中是统一惯例,例如 projects/net10/open-api-9/Program.cs 中对 YAML 文档示例页同样使用 ExcludeFromDescription(); //This is not an API endpoint 注释明确意图。这样做可以保证生成的 OpenAPI 文档只包含真实 API,不掺杂导航页等噪音端点。
3. SSE 端点:TypedResults.ServerSentEvents + SseItem
真正的主角是这个端点:
app.MapGet("/todos/stream", (CancellationToken ct) => TypedResults.ServerSentEvents(GetTodosAsync(ct)))
.WithName("StreamTodos");
要点:
TypedResults.ServerSentEvents(...):返回一个类型化的text/event-stream结果。这是 ASP.NET Core 内置的 SSE 支持,负责协议细节(data:/id:/event:字段格式、自动 flush、取消令牌处理),无需手写协议实现;.WithName("StreamTodos"):为端点命名,便于在 OpenAPI 文档中生成稳定的operationId,也方便通过LinkGenerator按名生成链接;CancellationToken ct:由框架注入,客户端断开连接时会被触发。
4. 事件生产源:IAsyncEnumerable<SseItem>
static async IAsyncEnumerable<SseItem<Todo>> GetTodosAsync([EnumeratorCancellation] CancellationToken ct = default)
{
foreach (var todo in Todos.All)
{
yield return new SseItem<Todo>(todo) { EventId = todo.Id.ToString() };
await Task.Delay(1000, ct);
}
}
几个值得注意的细节:
SseItem<Todo>来自System.Net.ServerSentEvents命名空间(文件顶部的using System.Net.ServerSentEvents;),它是类型化的 SSE 事件载体:SseItem<T>包装一个Todo作为事件载荷,EventId属性对应 SSE 协议的id:字段;[EnumeratorCancellation]注解把外部传入的CancellationToken与异步迭代器的取消机制绑定,await Task.Delay(1000, ct)确保客户端断开时及时停止产出——示例故意用 1 秒间隔逐条推送,便于观察流式效果;- 数据源是静态列表(Program.cs):
public record Todo(int Id, string Title, bool Done);
public static class Todos
{
public static readonly List<Todo> All = [
new(1, "Learn ASP.NET Core 11", false),
new(2, "Write a micro sample", true)
];
}
Todo 是一个 record 类型,恰好会被 OpenAPI 工具链映射为 components/schemas/Todo。
itemSchema 在生成文档中的具体表现与验证方法
open-api-13 的 README 仅用一句话点明主题,但仓库的 projects/net11/TODO.md 中保留了该示例的完整设计意图与验证步骤,可作为深入理解文档输出的依据:
- Verify: fetch
/openapi/v1.json, confirmopenapi: 3.2.0and the SSE response hasitemSchemareferencing#/components/schemas/Todo.
据此,完整验证路径如下:
- 启动应用后访问
/openapi/v1.json,确认文档根部的版本字段:
{
"openapi": "3.2.0",
...
}
openapi: 3.2.0 说明文档确实按 OpenAPI 3.2 生成——且本项目无需任何显式版本配置,印证了 .NET 11 的默认行为。
- 定位
StreamTodos操作(对应GET /todos/stream),观察其text/event-stream响应内容。期望的结构大致为:
{
"paths": {
"/todos/stream": {
"get": {
"operationId": "StreamTodos",
"responses": {
"200": {
"content": {
"text/event-stream": {
"schema": {
"type": "array",
"items": {
"type": "object"
},
"itemSchema": {
"$ref": "#/components/schemas/Todo"
}
}
}
}
}
}
}
}
}
}
关键点在于:text/event-stream 媒体类型下的 schema 包含 itemSchema 字段,且其值引用 #/components/schemas/Todo。正是这个 itemSchema 让 API 消费者知道"每条 SSE 事件的 data 是一个 Todo 对象"——这正是 OpenAPI 3.2 新增能力的落地体现。
- 核对组件区,确认
components/schemas/Todo已生成,包含id、title、done等属性定义。
关键陷阱:不要直接返回 IAsyncEnumerable<SseItem>
TODO.md 中记录了该示例最重要的一个注意点:
README: note that returning
IAsyncEnumerable<SseItem<T>>directly would serialize as JSON instead of SSE — must go throughTypedResults.ServerSentEvents.
这是一个非常容易犯的错误:如果端点直接返回 IAsyncEnumerable<SseItem<Todo>>,框架的默认输出格式化器会把它当作普通对象流进行 JSON 序列化——你会得到一个 JSON 数组,而不是 SSE 事件流;同时 OpenAPI 文档中该响应的内容类型也会被错误描述为 application/json,itemSchema 也就无从谈起。
正确的做法(即本示例的做法)是始终经由 TypedResults.ServerSentEvents(GetTodosAsync(ct)) 包装:
// 错误:会被序列化为 JSON 数组
app.MapGet("/todos/stream", (CancellationToken ct) => GetTodosAsync(ct));
// 正确:显式声明为 text/event-stream,逐事件推送
app.MapGet("/todos/stream", (CancellationToken ct) =>
TypedResults.ServerSentEvents(GetTodosAsync(ct)));
只有经过 ServerSentEvents 包装,响应内容类型才会是 text/event-stream,OpenAPI 文档才能据此使用 itemSchema 描述逐事件载荷。
与仓库其他 SSE / OpenAPI 示例的关联
open-api-13 不是仓库中唯一的 SSE 或 OpenAPI 示例,阅读时可以互相参照,形成完整脉络:
- SSE 内置支持的基础用法:较早的 projects/sse/Program.cs 展示了
Results.ServerSentEvents()配合IAsyncEnumerable<string>的最简形态;projects/net10/sse-4/Program.cs 则展示了"混合事件类型"的进阶用法——同一个流里交替产出SseItem<string>(..., "greeting")与不带事件名的SseItem<string>(...),客户端通过EventSource.addEventListener('greeting', ...)区分处理。open-api-13 中SseItem<Todo>的EventId用法与这些示例一脉相承。 - OpenAPI 版本演进:projects/net11/open-api-12 展示 HTTP QUERY 方法,其中仍需通过
options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_2显式指定版本;而 open-api-13 无需配置即为 3.2,可作为对照理解 .NET 11 的默认值变化。仓库 projects/net11/README.md 对 open-api-13 的定位描述是:"OpenAPI 3.2 as the default document version and theitemSchemadescription of Server-Sent Events responses",与本文解读完全一致。
小结
通过 practical-aspnetcore 的 open-api-13 示例可以看到,.NET 11 + OpenAPI 3.2 为 SSE 场景补齐了最后一块拼图:
- 版本默认化:.NET 11 中
AddOpenApi()默认生成 OpenAPI 3.2 文档,无需显式配置; - 响应描述标准化:OpenAPI 3.2 的
itemSchema让text/event-stream响应的逐事件载荷类型可以被文档精确描述(本示例中为#/components/schemas/Todo); - 类型化编程模型:
SseItem<T>提供强类型事件包装(含EventId),TypedResults.ServerSentEvents负责协议细节与取消处理; - 一个必须记住的边界:SSE 端点必须返回
TypedResults.ServerSentEvents(...)包装的结果,直接返回IAsyncEnumerable<SseItem<T>>会被当作 JSON 序列化。
对于需要公开 SSE 接口(如实时通知、进度推送、AI 流式输出)的 API 开发者而言,这套组合意味着:你的流式接口终于可以被 OpenAPI 工具链正确理解、生成客户端代码并参与契约测试,而不必再靠手工文档说明"每条事件的 data 是什么类型"。