WithOpenApi() ignore Api versioning readers

[Grzesiek23]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I'm encountering an issue with Swagger/OpenAPI documentation in my ASP.NET Core project, where I'm utilizing API versioning. When using WithOpenApi() method on my endpoints, Swagger documentation fails to generate correctly.

The problem occurs with Header or MediaType way of versioning.

Without WithOpenApi(), documentation for different API versions generates properly.

Expected Behavior

WithOpenApi() should allow for the correct generation of Swagger/OpenAPI documentation across different API versions.

Steps To Reproduce

Go and clone repo:
https://github.com/Grzesiek23/MinimalApiWithOpenApiProblem

Exceptions (if any)

No response

.NET Version

7 nad 8

Anything else?

No response

[commonsensesoftware]

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:

• Support Deprecation Metadata in the API Explorer aspnetcore#43493
• Produces and Accepts should target IEndpointConventionBuilder aspnetcore#43985

[commonsensesoftware]

@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?

[captainsafia]

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

[victor-priceputu-tb]

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