OpenAPI & Minimal APIs in ASP.NET Core 10.0

Asp.Net Core has continuously evolved to make building modern web applications and APIs faster, lighter, and more productive. With ASP.NET Core 10.0, developers get powerful improvements in Minimal APIs and OpenAPI integration. These updates simplify API design, reduce boilerplate, improve developer experience, and enhance interoperability with tools like Swagger UI , Postman , and client SDK generators .

In this article, we’ll explore what’s new, why it matters, and how to use these enhancements effectively.

1. Understanding Minimal APIs

Minimal APIs were first introduced in .NET 6 to provide a lightweight way of creating HTTP APIs without the overhead of controllers, attributes, or complex routing. Instead, you define endpoints directly in your Program.cs file.

Here’s a basic minimal API example in .NET 10:

  
    var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapGet("/", () => "Hello, ASP.NET Core 10 Minimal APIs!");

app.Run();

Instead of controllers, the request handling logic is expressed inline. This reduces ceremony, making it ideal for:

Microservices
Prototypes and demos
Lightweight REST APIs

2. What’s New in Minimal APIs in .NET 10

Asp.Net Core 10 builds on the foundation of Minimal APIs with:

Route groups with conventions – Organize endpoints logically.
Improved parameter binding – Cleaner support for complex types.
OpenAPI (Swagger) auto-generation improvements – Richer metadata and validation.
SSE (Server-Sent Events) – Real-time streaming support.
Enhanced filters and middleware integration – Greater flexibility.

3. OpenAPI in ASP.NET Core 10

OpenAPI (formerly known as Swagger) is the industry standard for describing REST APIs. It enables:

Documentation: Swagger UI lets developers explore APIs interactively.
Client SDK generation: Auto-generate clients in C#, TypeScript, Python, etc.
Validation: Ensures API contracts remain consistent.

In .NET 10, Microsoft has enhanced the OpenAPI package ( Microsoft.AspNetCore.OpenApi ) to work seamlessly with Minimal APIs .

4. Setting Up OpenAPI with Minimal APIs

Add the required package in your project file ( .csproj ):

  
    <ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.0" />
  <PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
</ItemGroup>

Then configure it in Program.cs :

  
    var builder = WebApplication.CreateBuilder(args);

// Add OpenAPI services
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

// Enable middleware for Swagger
if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

// Define Minimal API endpoints
app.MapGet("/api/products", () =>
{
    return new[]
    {
        new Product(1, "Laptop", 1200),
        new Product(2, "Phone", 800)
    };
})
.WithName("GetProducts")
.WithOpenApi();

app.Run();

record Product(int Id, string Name, decimal Price);

Key Enhancements in .NET 10

.WithOpenApi() automatically generates documentation for endpoints.
Models ( Product ) are described in the OpenAPI schema.
Swagger UI displays full details without extra configuration.

5. Route Groups in Minimal APIs

.NET 10 introduces Route Groups, which make organizing endpoints easier.

  
    var products = app.MapGroup("/api/products");

products.MapGet("/", () =>
{
    return new List<Product>
    {
        new(1, "Tablet", 500),
        new(2, "Smartwatch", 200)
    };
})
.WithOpenApi();

products.MapGet("/{id:int}", (int id) =>
{
    return new Product(id, "Generated Product", 99.99m);
})
.WithOpenApi();

✅ All routes under /api/products are grouped.
✅ Swagger displays them neatly under a single section.

6. OpenAPI Metadata Enrichment

You can enrich OpenAPI docs using endpoint metadata:

  
    products.MapPost("/", (Product product) =>
{
    return Results.Created($"/api/products/{product.Id}", product);
})
.WithName("CreateProduct")
.WithOpenApi(op =>
{
    op.Summary = "Creates a new product";
    op.Description = "Adds a product to the catalog with details like name and price.";
    return op;
});

This makes the Swagger UI highly descriptive with summaries and descriptions .

7. Complex Parameter Binding

Minimal APIs now support cleaner parameter binding.

  
    products.MapPut("/{id:int}", (int id, ProductUpdate update) =>
{
    return Results.Ok(new Product(id, update.Name, update.Price));
})
.WithOpenApi();

record ProductUpdate(string Name, decimal Price);

✅ Complex request bodies like ProductUpdate are automatically parsed from JSON.
✅ OpenAPI correctly documents these models.

8. Filters in Minimal APIs

Filters add cross-cutting behaviors like validation or logging without middleware.

  
    products.MapPost("/validate", (Product product) =>
{
    if (string.IsNullOrWhiteSpace(product.Name))
        return Results.BadRequest("Name is required");

    return Results.Ok(product);
})
.AddEndpointFilter(async (context, next) =>
{
    Console.WriteLine("Before executing endpoint");
    var result = await next(context);
    Console.WriteLine("After executing endpoint");
    return result;
})
.WithOpenApi();

✅ Filters improve reusability, and OpenAPI reflects validation details.

9. Server-Sent Events (SSE) in Minimal APIs

Streaming real-time updates is now simpler:

  
    app.MapGet("/notifications", async context =>
{
    context.Response.Headers.Add("Content-Type", "text/event-stream");
    for (int i = 1; i <= 5; i++)
    {
        await context.Response.WriteAsync($"data: Notification {i}\n\n");
        await context.Response.Body.FlushAsync();
        await Task.Delay(1000);
    }
}).WithOpenApi();

✅ Swagger documents the endpoint, though SSE testing is best via Postman or browsers.

10. Security with OpenAPI

You can define security schemes like JWT Bearer authentication in Swagger.

  
    builder.Services.AddSwaggerGen(options =>
{
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme
    {
        In = ParameterLocation.Header,
        Description = "Enter JWT with Bearer prefix",
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey
    });

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

✅ Swagger UI now includes a “Authorize” button for JWT authentication.

11. Benefits of OpenAPI & Minimal APIs in .NET 10

🚀 Developer Productivity: Write fewer lines of code.
📖 Auto Documentation: Swagger/OpenAPI keeps docs updated.
🔗 Integration Ready: Generate SDKs for Angular, React, Python, etc.
🧪 Improved Testing: Swagger UI doubles as an interactive test client.
⚡ Performance: Minimal APIs are faster to start and lighter than MVC controllers.

12. Example: Full Program.cs

  
    var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

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

var products = app.MapGroup("/api/products");

products.MapGet("/", () =>
    new List<Product>
    {
        new(1, "Laptop", 1200),
        new(2, "Phone", 800)
    })
.WithOpenApi();

products.MapPost("/", (Product product) =>
    Results.Created($"/api/products/{product.Id}", product))
.WithOpenApi(op =>
{
    op.Summary = "Create a new product";
    op.Description = "Adds a product with name and price to the catalog.";
    return op;
});

app.Run();

record Product(int Id, string Name, decimal Price);

Conclusion

Asp.Net Core 10.0 takes Minimal APIs and OpenAPI integration to the next level. Developers can now:

Build lightweight APIs with minimal boilerplate.
Automatically generate and enrich documentation.
Organize endpoints better with route groups.
Use filters for cross-cutting concerns.
Stream updates via SSE.
Secure APIs with built-in OpenAPI security definitions.

The combination of Minimal APIs and OpenAPI in .NET 10 ensures that APIs are not only fast and efficient but also well-documented, secure, and integration-friendly. This makes ASP.NET Core 10 a powerful choice for microservices, mobile backends, and modern web APIs.