Add better warnings about WithOpenApi potentially being useless #59927
Description
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.
Hi!
In #59180 the following is said:
Prior to .NET 9, we supported a WithOpenApi extension method on that when invoked would generate an OpenApiOperation, inject it into endpoint metadata, then rely on consuming OpenAPI implementations like Swashbuckle to pluck this OpenApiOperation and integrate it into the document that was being generated.
When we introduced built-in OpenAPI support in .NET 9, we opted not to bring in support for this strategy and instead steer people towards the new IOpenApiOperationTransformer abstraction for making modifications to their OpenAPI document.
I've been playing around a lot with Microsoft.AspNetCore.OpenApi. I tried to use WithOpenApi to edit some parameter descriptions, change operation responses, etc... It seemed a lot easier than creating a global transformer (which is why I am so happy about #59180 !). I was pulling my hair out, because it didn't work at all. The debugger told me things were being added to the OpenAPI definitions, but they weren't showing up in the document.
Then, by chance, I read the XML comments:
This method does not integrate with built-in OpenAPI document generation support in ASP.NET Core and is primarily intended for consumption along-side Swashbuckle.AspNetCore.
Now that Microsoft.AspNetCore.OpenAPI supports document generation, it's really weird that WithOpenApi does not play along.
This cost me quite a bit of time. The fact that I had to find it in the XML comments is not obvious enough.
Therefore, I believe we should do better than XML comments.
Describe the solution you'd like
Analyzer
Therefore, I believe we should consider either adding an analyzer that warns people about WithOpenApi being a no-op when only using Microsoft.AspNetCore.OpenApi.
This way it's way more obvious when you're doing something wrong. It will save a lot of time and frustration.
Deprecation
Perhaps we should even deprecate WithOpenApi and let Swashbuckle/NSwag deal with this on their own? This would be a breaking change, though.. But maybe for the best?
I really wonder why ASP.NET Core's own OpenAPI generation library should have methods that are only used by 3rd party libraries.
Now that Swashbuckle's not included by default anymore, WithOpenApi is code that is included in most (new) ASP.NET Core projects that won't do anything, and can only cause confusion. I do not remember anything like this in ASP.NET Core's public API like this, though that may also be ignorance.
Additional context
No response