OpenAPI 3.2 Support for Server Sent Events

[desjoerd]

Is there an existing issue for this?

• I have searched the existing issues

Is your feature request related to a problem? Please describe the problem.

No response

Describe the solution you'd like

OpenAPI 3.2 supports sequential media types like Server Sent Events (see https://learn.openapis.org/specification/media-types).
This feature request is to add built-in support for operations returning SseItems (see https://learn.microsoft.com/en-us/aspnet/core/fundamentals/minimal-apis/responses?view=aspnetcore-10.0#server-sent-events-sse)

Additional context

Requires Microsoft.OpenApi to be updated to 3.x (#64368)

[MihuBot]

I'm a bot. Here are possible related and/or duplicate issues (I may be wrong):

• Add support for emitting ServerSentEvents from minimal APIs #56172
• SseItem response in Results.ServerSentEvents #64183

[baywet]

Hi @desjoerd
Thank you for using the SDK and for reaching out.

I'm NOT on the ASP.NET team but I work on the OpenAPI standard and the dotnet implementation which ASP.NET relies on to emit the descriptions.

We've made some progress towards this with #63754 and #65415.

As far as I understand, this is how SSE is typically implemented in net10 these days

using System.Net.ServerSentEvents;
using System.Text.Json;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/sse", () =>
{
    async IAsyncEnumerable<SseItem<WeatherUpdate>> WeatherStream(CancellationToken ct)
    {
        for (var i = 0; i < 5; i++)
        {
            if (ct.IsCancellationRequested)
                yield break;

            yield return new SseItem<WeatherUpdate>(
                new WeatherUpdate(
                    TemperatureC: Random.Shared.Next(-10, 35),
                    Condition: "Sunny",
                    Timestamp: DateTime.UtcNow
                ),
                "weather-update"
            )
            {
                EventId = i.ToString()
            };

            await Task.Delay(1000, ct);
        }
    }

    return TypedResults.ServerSentEvents(
        WeatherStream
    );
});

app.Run();

public record WeatherUpdate(int TemperatureC, string Condition, DateTime Timestamp);

Relevant documentation:

• https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.typedresults.serversentevents?view=aspnetcore-10.0#microsoft-aspnetcore-http-typedresults-serversentevents-1(system-collections-generic-iasyncenumerable((system-net-serversentevents-sseitem((-0)))))
• https://learn.microsoft.com/en-us/dotnet/api/system.net.serversentevents.sseitem-1.eventid?view=net-10.0

We'd probably need an extension method/attributes to map the event types to event schemas for for discovery.

In turns, this should assign the ItemSchema property of the response, and result in a description for the operation response that looks something like that:

• https://spec.openapis.org/oas/v3.2.0.html#special-considerations-for-server-sent-events
• https://spec.openapis.org/oas/v3.2.0.html#server-sent-event-streams

There's still some design to do here, but hopefully this is a basis for discussion.

Let me know if you have any additional comments or questions.

[desjoerd]

I will check this :). I think it should be possible based on the info of the Api Explorer.