Microsoft.OpenAPI 2.0.0.0 has breaking changes

[bhrugen]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

In the previous version of Microsoft.OpenAPI we had the following

public OpenApiSecurityScheme(OpenApiSecurityScheme securityScheme)
 {
     Type = securityScheme?. Type ?? Type;
     Description = securityScheme?. Description ?? Description;
     Name = securityScheme?. Name ?? Name;
     In = securityScheme?. In ?? In;
     Scheme = securityScheme?. Scheme ?? Scheme;
     BearerFormat = securityScheme?. BearerFormat ?? BearerFormat;
     Flows = securityScheme?. Flows != null ? new(securityScheme?. Flows) : null;
     OpenIdConnectUrl = securityScheme?. OpenIdConnectUrl != null ? new Uri(securityScheme.OpenIdConnectUrl.OriginalString, UriKind.RelativeOrAbsolute) : null;
     Extensions = securityScheme?. Extensions != null ? new Dictionary<string, IOpenApiExtension>(securityScheme.Extensions) : null;
     UnresolvedReference = securityScheme?. UnresolvedReference ?? UnresolvedReference;
     Reference = securityScheme?. Reference != null ? new(securityScheme?. Reference) : null;
 }

But they remove the reference in version 2.0.0.0 and also i believe there are some breaking changes since if i use .NET 10 preview 2 to add securityrequirement it does not work at all

Previously what works in .NET 9 is below

builder. Services.AddSwaggerGen(options =>
{
    options. AddSecurityDefinition("JwtBearerDefaults.oa", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
    {
        Description =
            "JWT Authorization header using the Bearer scheme. \r\n\r\n " +
            "Enter 'Bearer' [space] and then your token in the text input below.\r\n\r\n" +
            "Example: \"Bearer 12345abcdef\"",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Scheme = JwtBearerDefaults.AuthenticationScheme,

});
    options. AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                },
                In = ParameterLocation.Header,
            },
            new List<string>()
        }
    });
});

but if i add it exactly in program.cs after adding the swashbuckle nuget package it does not work in .NET 10 Preview 2 Web API

Is there a workaround for this?

Expected Behavior

it should work as expected like in .NET 9

Steps To Reproduce

create a new .net 10 preview 2 web api project.

add swashbuckle nuget package

add the following in program.cs

builder. Services.AddSwaggerGen(options =>
{
    options. AddSecurityDefinition("JwtBearerDefaults.oa", new Microsoft.OpenApi.Models.OpenApiSecurityScheme
    {
        Description =
            "JWT Authorization header using the Bearer scheme. \r\n\r\n " +
            "Enter 'Bearer' [space] and then your token in the text input below.\r\n\r\n" +
            "Example: \"Bearer 12345abcdef\"",
        Name = "Authorization",
        In = ParameterLocation.Header,
        Scheme = JwtBearerDefaults.AuthenticationScheme,

});
    options. AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                },
                In = ParameterLocation.Header,
            },
            new List<string>()
        }
    });
});

Exceptions (if any)

No response

.NET Version

.NET 10 preview 2

Anything else?

No response

[martincostello]

Unfortunately this isn't bug, but a consequence of the huge breaking changes made in the Microsoft.OpenApi library for v2 that adds support for OpenAPI 3.1. Everything that builds on top of it, including ASP.NET Core and Swashbuckle needs to be updated to account for all the changes.

You can find further information in the release notes for .NET 10 preview 1 in the dotnet/core repository here.

You can follow this issue here for support for this in Swashbuckle: domaindrivendev/Swashbuckle.AspNetCore#2349 (comment)

Swashbuckle.AspNetCore isn't yet compatible with .NET 10 preview 2.

[captainsafia]

@martincostello's note in spot on here.

This issue filed by Martin on the Microsoft.OpenApi repo (microsoft/OpenAPI.NET#1973) tracks adding migration docs.

We've been doing our best to document the affected surface area in the What's New for ASP.NET Core, but eventually documentation for this should land on the Microsoft.OpenApi docs package.

I'm closing this issue out as external for now and we can track this on the Microsoft.OpenApi side.

[pholpar]

Forget AddSwaggerGen. I had today the same issue after updating our project from .NET 9 to .NET 10 (release). I found the solution (workaround?) Kamel Mojawaz posted just yesterday. See the comment on the page https://medium.com/@sidharth.cp34/openapi-swagger-enhancements-in-asp-net-core-10-the-complete-2025-guide-2fa6da93a7fb (it is a little bit hidden in the comment hierarchy).

"I solved this today. No need for SwaggerGen. The only package I installed is SwaggerUI.
Here I implemnted API Key & Bearer, you can remove API Key parts."

The original code from the comment:

builder.Services.AddOpenApi(options =>
{
 options.AddDocumentTransformer<SecuritySchemeTransformer>();
});

if (app.Environment.IsDevelopment())
{
  app.MapOpenApi();
  app.UseSwaggerUI();
}

internal sealed class SecuritySchemeTransformer : IOpenApiDocumentTransformer
{
  public Task TransformAsync(OpenApiDocument document, OpenApiDocumentTransformerContext context, CancellationToken cancellationToken)
  {
    document.Components ??= new OpenApiComponents();
    document.Components.SecuritySchemes ??= new Dictionary<string, IOpenApiSecurityScheme>();

    document.Components.SecuritySchemes["ApiKey"] = new OpenApiSecurityScheme
    {
      Type = SecuritySchemeType.ApiKey,
      Name = "X-API-KEY",
      In = ParameterLocation.Header,
      Description = "API key authentication"
    };

    document.Components.SecuritySchemes["Bearer"] = new OpenApiSecurityScheme
    {
      Type = SecuritySchemeType.Http,
      Scheme = "bearer", // "bearer" refers to the header name here
      In = ParameterLocation.Header,
      BearerFormat = "Json Web Token",
      Description = "Jwt authentication"
    };

    // Iterate through each path & operation
    foreach (var path in document.Paths.Values)
    {
      foreach (var operation in path.Operations.Values)
      {
        operation.Security ??= new List<OpenApiSecurityRequirement>();
        operation.Security.Add(new OpenApiSecurityRequirement
        {
          [new OpenApiSecuritySchemeReference("ApiKey", document)] = new List<string>(),
          [new OpenApiSecuritySchemeReference("Bearer", document)] = []
        });
      }
    }

    return Task.CompletedTask;
  }
}

Source referenced in the comment:
https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/customize-openapi?view=aspnetcore-10.0

My 2 cents:
Remember that you might have to add further options when invoking UseSwaggerUI.
For example,
options.SwaggerEndpoint("/openapi/v1.json", "StandardApi-v1");
or other ones, specific to your auth. method.
In my case (OAuth):

options.OAuthClientId(clientId);
options.OAuthUseBasicAuthenticationWithAccessCodeGrant();

[navyjax2]

I was able to make it work with Swashbuckle.AspNetCore, Swashbuckle.AspNetCore.Swagger, Swashbuckle.AspNetCore.SwaggerGen, and Swashbuckle.AspNetCore.SwaggerUI all at v8.0.0, installed alongside Microsoft.AspNetCore.OpenApi (v8.0.24) and OpenApi (1.6.28) using .NET 8.0. If I upgrade OpenApi to 2.* or the Swagger to v10 is when the bug appears from bhrugen's post.

In AddSwaggerGen, it needs:

options.SwaggerDoc("v1", new OpenApiInfo {
Title = "My Management API",
Version = "v1",
Description = "Management System",
Contact = new OpenApiContact
{
Name = "Support",
Email = "blah@blah.com"
}
});

Add CORS handling, authentication, authorization, any other projects, API services mapping to builder, then later:
var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI();

... any custom middleware... authentication/authorization....

app.Run();

[asrichesson]

The documentation on https://learn.microsoft.com/en-us/aspnet/core/fundamentals/openapi/customize-openapi?view=aspnetcore-10.0
needs to be updated with the recent breaking changes