OpenAPI and Swagger have become essential tools for documenting and testing APIs in ASP.NET Core 10. With the release of .NET 10, Microsoft has introduced a series of improvements. These changes make API documentation easier and cleaner. The improvements also align better with modern development practices.
These updates benefit Minimal APIs, versioned services, and even Native AOT applications, reducing boilerplate and improving the overall developer experience.
First‑Class OpenAPI Support for Minimal APIs
Minimal APIs now integrate directly with OpenAPI without extra dependencies. A simple configuration generates complete documentation:
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
var app = builder.Build();
app.MapGet("/weather", () =>
{
return new { Temperature = "25°C", Condition = "Sunny" };
})
.WithName("GetWeather")
.WithOpenApi();
app.UseSwagger();
app.UseSwaggerUI();
app.Run();
The .WithOpenApi() extension automatically infers metadata and schema details, making Minimal APIs feel fully supported.
Smarter Schema Generation
ASP.NET Core 10 includes a more capable schema generator that handles:
- Nested object structures
- Nullable types
- Enum descriptions
- Collections and generic responses
Swagger UI now reflects your real data contracts with minimal manual configuration.
Built‑In API Versioning Support
Generating separate OpenAPI documents for each API version is now straightforward:
builder.Services.AddApiVersioning(options =>
{
options.DefaultApiVersion = new ApiVersion(1, 0);
options.AssumeDefaultVersionWhenUnspecified = true;
})
.AddApiExplorer(options =>
{
options.GroupNameFormat = "'v'VVV";
options.SubstituteApiVersionInUrl = true;
});
Each version appears as its own selectable document in Swagger UI, making it easier to evolve your API safely.
Improved Swagger UI Customisation
The updated Swagger UI supports modern themes, dark mode, and OpenAPI 3.1. Custom branding is simple:
app.UseSwaggerUI(options =>
{
options.DocumentTitle = "My API Explorer";
options.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1");
options.InjectStylesheet("/swagger-ui/custom.css");
});
Add your own CSS to match your brand’s colors, layout, or logo.
Native AOT Compatibility
OpenAPI and Swagger now work seamlessly with Native AOT publishing. No reflection issues, no missing metadata.
dotnet publish -p:PublishAot=true
This is ideal for high‑performance microservices and lightweight deployments.
Richer Metadata with .WithOpenApi()
You can now customise endpoint documentation directly:
app.MapPost("/login", (LoginRequest request) =>
{
return Results.Ok("Logged in successfully");
})
.WithOpenApi(op => new(op)
{
Summary = "User Login Endpoint",
Description = "Authenticates a user and returns a JWT token.",
Tags = ["Authentication"]
});
This produces clearer, more helpful documentation for consumers.
Securing Swagger in Production
Restrict Swagger to development environments:
if (app.Environment.IsDevelopment())
{
app.UseSwagger();
app.UseSwaggerUI();
}
Or secure it with JWT:
builder.Services.AddSwaggerGen(c =>
{
c.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
{
In = ParameterLocation.Header,
Description = "Enter JWT with Bearer prefix",
Name = "Authorization",
Type = SecuritySchemeType.ApiKey
});
c.AddSecurityRequirement(new OpenApiSecurityRequirement {
{
new OpenApiSecurityScheme {
Reference = new OpenApiReference {
Type = ReferenceType.SecurityScheme,
Id = "Bearer"
}
},
new string[] {}
}});
});
Why These Updates Matter
- Cleaner, more accurate documentation
- Better performance with Native AOT
- Minimal APIs feel complete and production‑ready
- Versioning is easier to manage
- UI customisation is more flexible
ASP.NET Core 10 brings API documentation closer to enterprise‑grade standards with far less effort.
Final Thoughts
Microsoft’s 2025 improvements to OpenAPI and Swagger reflect a clear shift toward automation, clarity, and cloud‑native performance. Your API documentation is often the first thing developers see—these enhancements help ensure that first impression is polished and professional.
