Future of OpenApiOperation in endpoint metadata

[captainsafia]

Hi everyone!

Filing this issue because I'd like to hear some perspectives on something I'm reasoning through in the Microsoft.AspNetCore.OpenApi implementation.

In .NET 7, we added support for the WithOpenApi endpoint extension method for minimal APIs. When this API was invoked, we would generate an OpenApiOperation associated with the endpoint using the OpenApiGenerator. This OpenApiOperation would be inserted into endpoint metadata. From there, we made a change so that Swashbuckle would consume the OpenApiOperation that was present in metadata and insert it into the document it was generating (see here).

Now that built-in OpenAPI document generation is supported in Microsoft.AspNetCore.OpenApi, I am trying to figure out what the best path forward WithOpenApi and OpenApiOperation in metadata is. Here's some of the options on the table:

1. Do nothing: Keep WithOpenApi and OpenApiGenerator as detached from the new document generation in Microsoft.AspNetCore.OpenApi.
2. Deprecate WithOpenApi and (eventually) remove logic for integrating OpenApiOperation from metadata into Swashbuckle's document.
3. Replat WithOpenApi as shorthand for producing an operation transformer but remove functionality for inserting the OpenAPI operation into metadata for Swashbuckle to consume.
4. Replat WithOpenApi as shorthand for producing an operation transformer and project the OpenApiOperation from the built-in document into metadata for Swashbuckle to consume.

Of the options above, #4 is probably the most expensive to implement but retains the most amount of behavior for users. #1 is cheap but doesn't leave users in a good place WRT whether they should use WithOpenApi at all.

Thoughts?