Microsoft.AspNetCore.OpenApi: Support API versioning (required for Swashbuckle feature parity)

[josundt]

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.

We currently use .NET 8.0/AspNetCore with Swashbuckle.AspNetCore in many APIs in our product ecosystem.
The current OpenApi documentations are very good with multiple API versions, good descriptions/comments, security defs/refs etc.

Swashbuckle.AspNetCore integrates with the package Asp.Versioning.Mvc.ApiExplorer to enable and simplify API versioning.
It augments SwashBuckle's capabilities (that we currently depend upon):

• Tagging with Controllers/Action Methods with [ApiVersion("version")] attributes.
  These attributes add metadata describing in which version(s) the Controllers/ActonMethods are included.
• Using special {version:apiVersion} route parameters that maps/has constraints to the tagged versions for Controller/ActionMethod.

Swashbuckle parses this metadata to enable splitting into multiple OpenApi documents - one JSON file per version.

I think the currently way of managing API versioning is simple and it works very well, and I hope the goal for Microsoft.AspNetCore.OpenApi is to get close to feature parity with Swashbuckle.AspNetCore and to make migration as easy as possible.

Describe the solution you'd like

This is a feature request to support API versioning, hopefully a similar way.
I don't know if you plan to integrate with Asp.Versioning.Mvc.ApiExplorer, but hope you can use similar concepts.

Can you ellaborate about the current plans to support API versioning?

Additional context

No response

[captainsafia]

@josundt Thanks for filling this issue!

Things actually work the other way around with respect to API versioning + OpenAPI in ASP.NET Core.

The Asp.Versioning.Mvc.ApiExplorer package that you referenced above integrates with ASP.NET Core's API explorer implementation. API explorer allows frameworks to expose an implementation of IApiDescriptionProvider that consumers can inspect to generate OpenAPI documentation.

All OpenAPI implementations in the ASP.NET ecosystem depend on API Explorer (NSwag, Swashbuckle, and our own Microsoft.AspNetCore.OpenApi) and can pick up the additional metadata that Asp.Versioning adds to the ApiExplorer interfaces in order to access versioning information.

With regard to how the new Microsoft.AspNetCore.OpenApi package integrates with Asp.Versioning, check out this PR on the eShop repo for an example of what the delta between the two implementations is.

Have you tried using Microsoft.AspNetCore.OpenApi in a project alongside Asp.Versioning and ran into issues?

[captainsafia]

Removing the No Recent Acitivity label to give @josundt a chance to comment on the question below before the bot auto-closes.

Have you tried using Microsoft.AspNetCore.OpenApi in a project alongside Asp.Versioning and ran into issues?

[josundt]

@captainsafia I'll try to perform a test migration of one of one of our APIs by looking at eShop repo today or tomorrow. I'll get back to you 👍

[josundt]

@captainsafia
I have eventually been able to do a PoC of a .NET 9.0 (preview) API using the following NuGet packages:

• Microsoft.AspNetCore.OpenApi
• Asp.Versioning.Mvc.ApiExplorer
• Microsoft.Extensions.ApiDescription.Server

After studying the eShop repo PR you mentioned, I managed to get a simple API running with two API versions (separate OpenAPI documents per version) and build-time OpenAPI documents generation.

You can see my small sample project here.

Findings/feedback:

1. Schema duplication
   SwashBuckle added all complex type (and enum) schemas as single instance JSON objects in
   the OpenAPI document under #/components/schemas.
   HTTP operations that referred to the schemas through request parameters, requestBody or responses used JSON Pointer $ref references.
   Microsoft.AspNetCore.OpenApi currently serializes the same schema multiple times, thereby
   increasing the size of the OpenAPI document drastically. Even if the schema "multiplication" is
   not directly wrong logically speaking, the relationships between the shared
   Schemas and the different HTTP operations are no longer expressed. This is crucial for the various tools that
   generate code from OpenAPI documents. I hope there's a plan to support this on your roadmap.

2. ProblemDetails Content-Type
   AspNetCore makes sure that non-success ProblemDetails responses at runtime get the
   response Content-Type header set to "application/problem+json".
   (You can test this through my sample api's ErrorDemoController using the
   AspNetCore.SampleOpenApi.http file).

   But: The swagger document reports "application/json" for such responses still, so there's
   inconsistency between OpenAPI documentation and the actual API behavior.

   FYI: This problem was the same with SwashBuckle, so with that package I needed to make a
   "OperationFilter" class to get the documentation right. I was able to do the same thing
   using an OperationTransformer in Microsoft.AspNetCore.OpenApi, but this should ideally be
   handled by the package out-of-the-box.

3. Inclusion of XML comments for extended descriptions in OpenAPI documents
   SwashBuckle capabilities included extraction of XML comments from Controller action methods
   with parameters and returns and add this information to the OpenAPI documents. I can not see
   that this is a built-in feature of Microsoft.AspNetCore.OpenApi yet.

4. Removing redundant response content-types
   In a standard AspNetCore API, OpenAPI documents' response status content will have 3 content-types;
   "text/plain", "application/json" and "text/json".
   In a well-designed JSON API, only "application/json" is desirable/required.
   I have added code to my repository to remove the redundant output formatters and media types
   here.
   I think this is typically what people want in their APIs, and I suggest that something similar
   is added to your documentation.

5. Complexity of using OpenAPI with API versioning
   The code in my OpenApiOptionsExtensions.cs is more or less an exact copy of what I found in
   the eShop PR. This code is in my opinion quite low-level and it will probably be hard to get
   this right for consumers/customers. I spent quite some time myself before finding those magical
   lines that glues it all together. This needs be simplified somehow; what about including
   code in the package and calling the extension method
   UseDefaultVersioning(this OpenApiOptions options, ...) or similar?

6. Documentation for API versioning
   The integration between Microsoft.AspNetCore.OpenApi and Asp.Versioning.Mvc.ApiExplorer
   needs better documentation on your documentation page
   before the package is made generally available for the .NET 9.0 release.

[josundt]

@captainsafia I have not received any feedback on this.
In the comment above I have described the currently missing features Microsoft.AspNetCore.OpenApi preventing a complete migration from SwashBuckle in our products.
Could you please share some information on whether or not each of these features are on the roadmap for the final .NET 9.0 release?

[martincostello]

Schema duplication

This was implemented by #56175 and initial support will be in preview 6, with further changes in preview 7.

Other things you've mentioned such as XML documentation support and versioning are in the OpenAPI epic: #54598

[captainsafia]

@josundt Apologies for the delay here! My focus has been on dev-related work over the past few weeks as we barrel closer to RC1. 😄

Schema duplication

I think @martincostello provided a great answer here. This space has been evolving in reaction to customer feedback. I'd recommend trying the latest nightly bits of the package to see where things currently are and sharing your feedback there.

ProblemDetails Content-Type

The issue that you're describing here is a limitation of the way that ProblemDetails responses are modeled in the ApiExplorer metadata. By default, if you are returning a ProblemDetails-type result from an API (either controller-based or minimal APIs), we will not add any metadata to the ApiExplorer that describes what that result would be.

This is primarily because we don't have a good way of inferring the HTTP status code that your error result is associated with, which is the primary key for response schemas in both ApiExplorer and OpenAPI. To fix this, you need to clue the famework in on what type of response your ProblemDetails is assocaited with by adding the metadata yourself (either via ProducesResponseType attributes or via a ProducesProblem method call on a minimal API).

As a converse to this, you'll observe that the ValidationProblem type in TypedResults does provide the correct metadata by default. That's because there, we can make an inference that your status code is 4xx based on the semantics of the platform.

TL;DR: The lack of specificity ProblemDetails here is intentional and is a deficiency in the underlying ApiExplorer layer and our ability to make automatic inferences about result types.

#52424 is another bug report around this in case you'd like to thumbs that up or chime in there.

Inclusion of XML comments for extended descriptions in OpenAPI documents

Yep, XML support isn't in yet. I've been playing around in this space though and hope to post an update on this issue (#39927) for it soon.

Removing redundant response content-types

I think the scenario that you are describing here is specific to controller-based APIs in MVC, where users have more flexibility to configure output formatters than they do in minimal APIs. In minimal APIs, the only content-types we'll automatically infer are application/json and text/plain.

In this case, ApiExplorer is doing its best to present an accurate representation of what outputs your API might return based on MVC's default output formatting configuration (which supports writing to multiple response content-types by default).

In this case, the action that you've taken is one way to clue in the system that you want to restrict the types of response content-types that are supported. Explicitly setting the Produces attribute on your handler is another way to do this.

With respect to documenting this officially, we do cover it in this section of the docs. I'm a little hesitant to include it in the top-level OpenAPI-docs given it is (a) MVC-specific and (b) more relevant to output formatting/content negotation than it is OpenAPI.

This needs be simplified somehow; what about including
code in the package and calling the extension method
UseDefaultVersioning(this OpenApiOptions options, ...) or similar?

Yep, this is a good observation. You might've noticed that the same transformation code is applied in the Asp.Versioning samples for both Swashbuckle and Microsoft.AspNetCore.OpenApi. I agree with you that it probably makes sense for the Asp.Versioning package to provide these as first-class APIs for both implementations so that users don't have to copy them into application code. Would you be able to file an issue on the Asp.Versioning repo for this?