Updating OpenAPI 3.2 Documentation in ASP.NET Core Without Breaking Existing Clients

OpenAPI documentation plays an important role in modern ASP.NET Core applications. It describes API endpoints, request parameters, response formats, authentication requirements, and error responses. Developers use this information to generate client libraries, integrate external services, and understand how an API behaves.

As APIs evolve, their documentation standards also change. OpenAPI 3.2 introduces improvements that help describe modern API capabilities, including HTTP QUERY operations, Server-Sent Events, and more accurate response schemas.

ASP.NET Core provides built-in OpenAPI document generation through the Microsoft.AspNetCore.OpenApi package. However, moving to a newer OpenAPI specification is not always a simple configuration change. Existing API consumers may depend on older documentation formats, and some code generators, validation tools, and API management platforms may not fully support the newer specification.

The important point is that upgrading OpenAPI documentation should not automatically require changing the actual API contract.

In this article, we will explore how OpenAPI 3.2 works in ASP.NET Core, how to configure it, and how to introduce the newer specification without unnecessarily affecting existing API clients.

Understanding OpenAPI 3.2 in ASP.NET Core

OpenAPI is a standard for describing HTTP APIs in a machine-readable format. It allows developers and tools to understand an API without examining its implementation.

An OpenAPI document typically describes:

• Available API endpoints and HTTP methods.
• Request parameters and request body schemas.
• Response status codes and response structures.
• Authentication and authorization requirements.
• Supported content types.
• Reusable schemas and components.

ASP.NET Core supports OpenAPI document generation through the Microsoft.AspNetCore.OpenApi package.

The supported default versions depend on the target framework:

Starting with .NET 11, ASP.NET Core generates OpenAPI 3.2 documents by default.

This does not mean existing APIs automatically change their HTTP behavior. The specification version describes the API contract in a document. It does not independently change endpoint routes, authentication rules, or response behavior.

However, tools that consume the document must understand the specification version and the features used in it.

Why Updating OpenAPI Can Affect Existing API Clients

Consider an ASP.NET Core application that exposes customer and order management APIs.

The application generates an OpenAPI document, which is consumed by several systems:

• A frontend application uses generated TypeScript clients.
• A mobile application team uses generated API models.
• An integration partner imports the specification into its development tools.
• An API management platform validates and publishes API definitions.
• Automated tests compare the generated document against an approved API contract.

Now imagine upgrading the application to .NET 11.

The generated OpenAPI document uses version 3.2 by default. Some existing tools may still expect OpenAPI 3.0 or 3.1.

This can introduce problems such as:

• Client generation failures.
• Unsupported schema features.
• Differences in generated models.
• Validation errors in older API management tools.
• Incompatible documentation imports.

It is important to understand that these problems do not necessarily indicate that the actual API endpoints are broken. They may be caused by differences in how downstream tools interpret the newer OpenAPI document.

Therefore, upgrading the documentation format should be treated as a compatibility exercise.

Configuring OpenAPI 3.2 in ASP.NET Core

Let's start with a basic ASP.NET Core application.

Step 1. Install the OpenAPI Package

Add the Microsoft.AspNetCore.OpenApi package to your ASP.NET Core project.

For a .NET 11 application, use the package version compatible with the target framework.

The project file should contain a package reference similar to the following:

<ItemGroup>
    <PackageReference
        Include="Microsoft.AspNetCore.OpenApi"
        Version="11.0.0" />
</ItemGroup>

Use the appropriate stable servicing version available for your project rather than assuming that every package version is interchangeable.

Step 2. Register OpenAPI Services

Open Program.cs and register OpenAPI document generation.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.Run();

The AddOpenApi method registers the services required to generate the OpenAPI document.

The MapOpenApi method exposes the generated document through an HTTP endpoint.

By default, the document is available at:

/openapi/v1.json

In .NET 11, the generated document uses OpenAPI 3.2 by default.

Step 3. Explicitly Configure the OpenAPI Version

Although .NET 11 uses OpenAPI 3.2 by default, explicitly configuring the version makes the application's intention clear.

using Microsoft.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_2;
});

var app = builder.Build();

app.MapOpenApi();

app.Run();

This configuration tells ASP.NET Core to generate an OpenAPI 3.2 document.

Explicit configuration is useful when maintaining multiple API projects because developers can identify the intended specification version without relying on framework defaults.

Maintaining Compatibility With Existing Clients

One of the safest approaches is to keep the existing OpenAPI version until all downstream consumers are ready for the newer format.

For example, an application upgraded to .NET 11 can continue generating an OpenAPI 3.1 document.

using Microsoft.OpenApi;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = OpenApiSpecVersion.OpenApi3_1;
});

var app = builder.Build();

app.MapOpenApi();

app.Run();

This allows the application to use the newer ASP.NET Core framework while retaining the previous documentation format.

It is particularly useful when:

• Existing client-generation tools do not support OpenAPI 3.2.
• External partners depend on the existing specification.
• API management platforms require additional time for compatibility updates.
• The organization needs to upgrade applications gradually.

An important distinction is that keeping OpenAPI 3.1 does not automatically preserve every detail of an earlier generated document. Framework upgrades can introduce changes in schema generation and metadata. Therefore, compare the generated documents before deploying the upgrade.

Supporting Multiple OpenAPI Documents

In larger applications, different consumers may have different compatibility requirements.

Instead of immediately replacing the existing document, you can generate multiple named OpenAPI documents.

For example, one document can target OpenAPI 3.1 for existing consumers, while another targets OpenAPI 3.2 for newer integrations.