使用 OpenAPI 3.2 的 itemSchema 描述 Server-Sent Events 响应:practical-aspnetcore 中 open-api-13 实战解析

原创2026-10-14 21:00:031,949 阅读
文章标签:示例工程

使用 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 itemSchema support so text/event-stream responses 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 是一个完整的微型可运行项目,目录结构如下:

项目文件(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 中声明的 SDK 11.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, confirm openapi: 3.2.0 and the SSE response has itemSchema referencing #/components/schemas/Todo.

据此,完整验证路径如下:

  1. 启动应用后访问 /openapi/v1.json,确认文档根部的版本字段:
{
  "openapi": "3.2.0",
  ...
}

openapi: 3.2.0 说明文档确实按 OpenAPI 3.2 生成——且本项目无需任何显式版本配置,印证了 .NET 11 的默认行为。

  1. 定位 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 新增能力的落地体现。

  1. 核对组件区,确认 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 through TypedResults.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 the itemSchema description of Server-Sent Events responses",与本文解读完全一致。

小结

通过 practical-aspnetcore 的 open-api-13 示例可以看到,.NET 11 + OpenAPI 3.2 为 SSE 场景补齐了最后一块拼图:

  1. 版本默认化:.NET 11 中 AddOpenApi() 默认生成 OpenAPI 3.2 文档,无需显式配置;
  2. 响应描述标准化:OpenAPI 3.2 的 itemSchema 让 text/event-stream 响应的逐事件载荷类型可以被文档精确描述(本示例中为 #/components/schemas/Todo);
  3. 类型化编程模型:SseItem<T> 提供强类型事件包装(含 EventId),TypedResults.ServerSentEvents 负责协议细节与取消处理;
  4. 一个必须记住的边界:SSE 端点必须返回 TypedResults.ServerSentEvents(...) 包装的结果,直接返回 IAsyncEnumerable<SseItem<T>> 会被当作 JSON 序列化。

对于需要公开 SSE 接口(如实时通知、进度推送、AI 流式输出)的 API 开发者而言,这套组合意味着:你的流式接口终于可以被 OpenAPI 工具链正确理解、生成客户端代码并参与契约测试,而不必再靠手工文档说明"每条事件的 data 是什么类型"。

登录后查看全文
practical-aspnetcore