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?

[martincostello]

My thoughts on the above:

1. Makes adopting the new things opt-in so keeps the distinction and maintains backwards compatibility. Doesn't break anything, but doesn't guide anyone to improvements.
2. Not a fan of this one - if we keep Swashbuckle up to date with .NET vNext each year, eventually working code for someone who doesn't want/need to migrate just stops working and then we have a weird "WithOpenApi works with .NET <=8, but beyond 9 it won't work anymore sorry" inconsistency.
3. Similar to the above, but the user benefits from the new functionality. It might lead to some weird halfway house though where stuff "disappears" from their Swashbuckle documents.
4. This is nice for users, but I guess undercuts the "use this instead" value proposition of the new shiny things and moving away from Swashbuckle as then it keeps working anyway and maybe creates a different halfway house as then people will come to Swashbuckle asking why new ASP.NET Core concepts aren't appearing in their documents. We'd then need to play catch-up emulating the new functionality, or just say "we don't support these new concepts, migrate to built-in OpenAPI support instead".

The halfway-house-ness is my biggest concern, but maybe it's unfounded? I'm just thinking out-loud here.

My knee-jerk reaction here is that 1 is the "safest", and that an additional gesture/overload/something is what users should use/move to if they want to go all in on the new shiny OpenAPI stuff and move away from Swashbuckle/NSwag/A.N.Other.

[captainsafia]

@martincostello Thanks for chiming in!

The "halfway-house-ness" is definitely a concern I share. I'm torn between whether we try to carry WithOpenApi to our new universe or just leave it as is.

Option 1 appeals to me because of its cheapness. The drawback of user confusion might not be a big deal if we're proactive about documenting what it is and why it doesn't make sense to use it in a post-.NET 8 world.

if we keep Swashbuckle up to date with .NET vNext each year, eventually working code for someone who doesn't want/need to migrate just stops working and then we have a weird "WithOpenApi works with .NET <=8, but beyond 9 it won't work anymore sorry" inconsistency.

Good point! There's a decent amount of usage of WithOpenApi in OSS code bases (see here) so deprecation may be jarring for people who want to make updates to dependencies without moving.

OK, given that Option 1 requires no engineering work (but some docs work), I'll move with that as the option. If we decide it was a bad choice, we can change it in the future.

I suppose that's another benefit of Option 1, it's the easiest one to "take back" if we decide to go with it. 😅