Swashbuckle 10 and SwaggerDefaultValues.cs

[martinRocks]

Is there an existing issue for this?

• I have searched the existing issues

Describe the bug

I'm upgrading my project for dot net 9 to dot net 10. I figured it would be good to use Swashbuckle.AspNetCore 10.1.0 also. The example code to get the swagger page to show my versions is SwaggerDefaultValues.cs and it seem that the parameter.Schema.Default is now only a getter so there is no setting it. Also, OpenApiAnyFactory is no longer a thing. And parameter.Required is a getter only. What do we do? I think the example needs to be updated.

``
foreach (var parameter in operation.Parameters)
{
var description = apiDescription.ParameterDescriptions.First(p => p.Name == parameter.Name);

parameter.Description ??= description.ModelMetadata?.Description;

if (parameter.Schema.Default == null && description.DefaultValue != null)
{
    var json = JsonSerializer.Serialize(description.DefaultValue, description.ModelMetadata.ModelType);
    parameter.Schema.Default = OpenApiAnyFactory.CreateFromJson(json);
}

parameter.Required |= description.IsRequired;

}
``

Expected Behavior

No response

Steps To Reproduce

No response

Exceptions (if any)

No response

.NET Version

No response

Anything else?

No response

[martinRocks]

maybe something like this? It seems to work.
`
foreach (OpenApiParameter parameter in operation.Parameters)
{
var description = apiDescription.ParameterDescriptions
.First(p => p.Name == parameter.Name);

parameter.Description ??= description.ModelMetadata?.Description;

if (parameter.Schema is OpenApiSchema openApiSchema)
{
    if (parameter.Schema.Default == null &&
        description.DefaultValue != null &&
        description.DefaultValue is not DBNull &&
        description.ModelMetadata is ModelMetadata modelMetadata)
    {
        var json = JsonSerializer.Serialize(description.DefaultValue, modelMetadata.ModelType);
        var element = JsonSerializer.Deserialize<JsonElement>(json);
        openApiSchema.Default = JsonValue.Create(element);
    }
}

parameter.Required |= description.IsRequired;

}
`

[commonsensesoftware]

.NET 10 is not officially supported - yet. The current version is still 8.1.x, but it seems like it worked for you in .NET 9. The .NET 10 work is underway and there are several new things coming. The forthcoming release will provide intrinsic support for Microsoft.AspNetCore.OpenApi and will likely see a transition away from Swashbuckle toward something like Scalar. The OpenAPI / Swagger support has never been about endorsing a particular library or approach, but rather the default of what tooling, templates, and walkthroughs take developers through. Swashbuckle was just the first and most popular for a long time. This is why there aren't any NSwag examples. Swashbuckle is still alive, but the original author has moved on from the project and Microsoft has pivoted away from it in their templates. As a one-man show, I have to be cognizant of what I support and where I draw boundaries. I'm not quite there - yet, so I can't say for sure, but I expect there won't be any more Swashbuckle examples. I might consider a new repo or other documentation that highlights integration, but I'm not sure yet. As you can see, keeping things in sync is a chore. Ultimately, this project and repo isn't about how to use OpenAPI or advocate a best practice, but rather show the minimum setup to get something working.

Your proposed workaround looks correct. One of the goals, at least for examples, is to avoid these special setups. These have long been gaps in Swashbuckle and other OpenAPI generators honoring the information provided by API Versioning API Explorer extensions.

[commonsensesoftware]

🎉 10.0 (Preview 1) has been released. This includes new, deep support for OpenAPI that should resolve this issue. No more .AddOpenApi("v1).AddOpenApi("v2") 🤮. It's simply .AddApiVersioning().AddOpenApi() and optionally configure it if you want to. The endpoint setup is now app.MapOpenApi().WithDocumentPerVersion(). There's a few more kinks to work out under the hood and few more features to go, but what people are looking for on this thread should be largely covered and stable. The examples have all been updated to showcase the new functionality, but have moved away from Swashbuckle to Scalar using Microsoft.AspNetCore.OpenApi. Document generation also works. 😉

All of necessary functionality exists to achieve a similar result with Swashbuckle, but I don't have the capacity to maintain a bridge between every Swagger/OpenAPI library.

[Frulfump]

.NET 10 is not officially supported - yet. The current version is still 8.1.x, but it seems like it worked for you in .NET 9.

First congrats on the new release. I don't think I see it documented in the README.md that this libraries major version follows the major version of the .NET LTS or what version is officially supported?

[commonsensesoftware]

A fair point and I do need to add something about that.

Mapping the major release version to the current .NET major version is a quick convenience to reason about, but it's not a hard and fast rule. What is a hard rule is the target framework moniker (TFM) has to match the version you are running on. Regardless of the library version, if the TFM doesn't match the version you are running against, it is not guaranteed to work. The 8.0 release targeted net8.0, which is not guaranteed to work if you roll it forward in .NET 9 or 10.

You might think that "Surely you can't be serious that a library isn't backward compatible if doesn't have any changes.". "I'm am serious and don't call me Surely." 😛 That seems rational, but it 100% has happened. It occurred when default interface members were introduced and for whatever reason, the ASP.NET team decided to have the default implementation throw new NotImplementedException(), which broke things when you rolled forward. This also just happened as recently as #1160. Incompatibility failures do not always manifest as compiler errors.

All that being said, if rolling forward happens to work - great. I'll hear pretty quickly if it doesn't. When it comes to what is officially supported, all libraries are supposed to be match the target TFM. Anything else is happenstance. In terms of library version support, my target is N-1 LTS versions. As a one-man army, I don't have the capacity for more. I rarely backport unless it is critical. Sadly, .NET 9 was the first iteration I didn't have an official release for. 😿

[tebeco]

🎉 10.0 (Preview 1) has been released. This includes new, deep support for OpenAPI that should resolve this issue. No more .AddOpenApi("v1).AddOpenApi("v2") 🤮. It's simply .AddApiVersioning().AddOpenApi() and optionally configure it if you want to. The endpoint setup is now app.MapOpenApi().WithDocumentPerVersion(). There's a few more kinks to work out under the hood and few more features to go, but what people are looking for on this thread should be largely covered and stable. The examples have all been updated to showcase the new functionality, but have moved away from Swashbuckle to Scalar using Microsoft.AspNetCore.OpenApi. Document generation also works. 😉

I have a very humble question, we started moving to net10 which lead to use OpenApi as well
The old code base is/was use NSwag/AspVersionning.

We stumbled over a consensus to use Scalar for now, and saw this issue eventually
You mentioned this:

No more .AddOpenApi("v1).AddOpenApi("v2") 🤮. It's simply .AddApiVersioning().AddOpenApi()
Last month, and until like 4 hours ago we were ok with removing AspNet.Versionning from company repos if having to list all version as build time was the new way.

Here's the unwanted question, do you have a ball parc estimate for 10.x version of AspNet.Versionning ?
It's all fine if it's accurate to like "end 2026" or "mid 202x"

It's just to have a perspective if we merge before without it and add it back later, or wait a bit.