As outlined in dotnet/aspnetcore#40676 and implemented in dotnet/aspnetcore#41238, we're introducing support for a new Microsoft.AspNetCore.OpenApi package that acts as a link between Microsoft.OpenApi and route handler endpoints.

This package exposes a WithOpenApi extension method that users can invoke on their endpoints to mutate the OpenApiOperation that we generate by default from the handler's MethodInfo with their own annotation. For example,

app.MapGet("/foo", () => {})
.WithOpenApi(generatedOperation => {
  generatedOperation.OperationId = "MadeByMe";
  return generatedOperation;
});

One of the things we thought would be compelling was support for a copy constructor for OpenApiOperation so that users can invoke the following and have their modification automatically merged into the generated operation.

app.MapGet("/foo", () => {})
.WithOpenApi(generatedOperation => new(generatedOperation) {
  OperationId = "MadeByMe"
});