WithOpenApi() ignore Api versioning readers about aspnet-api-versioning HOT 4 OPEN

@commonsensesoftware Hopefully, yes! Trying to dust of some prototypes and figure out a plan, ATM.

from aspnet-api-versioning.

Unfortunately, depending on what you are doing and what you expect, some things will not work as expected. Ultimately, this is a design flaw (IMHO) with how WithOpenApi works. I've had conversations with ASP.NET team about this, but I don't believe any changes made it into .NET 8. I'm not sure if it will be tackled in .NET 9 - yet.

The problem is that WithOpenApi adds a new OpenApiOperation as metadata directly to Endpoint.Metadata. Some OpenAPI tooling, like Swashbuckle, then look directly for this metadata without consulting the API Explorer. That is a problem. API Versioning does not directly care about Swashbuckle or OpenAPI. It does explore and provide all of the metadata via the API Explorer extensions, which is directly part of ASP.NET Core. Essentially, when you call WithOpenApi, all of the other goodness is being ignored, but it's not API Versioning doing it.

That is only the tip of the iceberg. API Versioning supports interleaving multiple versions on the same endpoint. That is not supported by WithOpenApi because it will only ever create a single OpenApiOperation. This can be quite problematic. Image you had 0.9 (deprecated) and 1.0. What you'll likely see happen is 0.9 will report deprecated, but so will 1.0 because there is only a single instance.

You can set a lot of other metadata as long as you don't do it through WithOpenApi. I've seen issues like this in the past. The two can technically be used together, but you might not get the results you expect. I have not seen media type come up before, but that might have been because people were not versioning by media type and an empty content type was expected to be application/json. If you can get around not using WithOpenApi, I would recommend it.

Opening or commenting on issues in the ASP.NET Core repo is likely to get better traction than what I do on my own. Here's a few existing issues related to this area:

• dotnet/aspnetcore#43493
• dotnet/aspnetcore#43985

from aspnet-api-versioning.

@captainsafia it doesn't seems the OpenAPI improvements made the .NET 8 cut line. Is there an epic or plan to improve this area for .NET 9 - yet?

from aspnet-api-versioning.

I was using exactly this and did not understand why the documentation does not get generated properly. I removed WithOpenApi and now it generates properly. thank you for raising this

from aspnet-api-versioning.