C#  

Why Scalar is Replacing Swagger in .NET 9 and 10

Introduction

Swashbuckle was long the ASP.NET Core standard and Microsoft's default for OpenAPI documentation. However, declining maintenance and departing contributors led to mounting issues and poor .NET 8 support. Consequently, Microsoft removed it from default templates in .NET 9, favoring native tools like Microsoft.AspNetCore.OpenApi and modern alternatives like Scalar.

By transitioning to a native solution, Microsoft provides a sustainable, long-term experience that eliminates the need for third-party tools. This shift toward first-class integrations—specifically via the Microsoft.AspNetCore.OpenApi package—ensures that the core tools we use daily are well-supported, tightly integrated, and future-proof.

What changed

In .NET 9, Microsoft replaced the third-party Swashbuckle dependency with native document generation via the Microsoft.AspNetCore.OpenApi package. By moving this process directly into the framework, Microsoft eliminated external dependencies for generating API specifications.

While the legacy .NET 8 template included Swashbuckle by default to provide both the OpenAPI JSON and the Swagger UI, the new standard focuses on native generation. Developers now typically pair this with modern UI tools like Scalat or NSwag for an interactive testing experience.

In .NET 8, the default configuration relied on Swashbuckle for both discovery and UI generation:

// .NET 8: Swashbuckle / Swagger Implementation
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

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

By contrast, .NET 9 introduces a streamlined, native approach using the Microsoft.AspNetCore.OpenApi package:

// .NET 9: Native OpenAPI Implementation
builder.Services.AddOpenApi();

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

This transition replaces external dependencies with built-in framework support, surfacing the API specification at /openapi/v1.json by default. To restore a visual testing interface, developers often now integrate Sclar alongside these native commands.

While Microsoft removed Swashbuckle from the default templates, you can still easily re-add a visual interface. Since the Microsoft.AspNetCore.OpenApi package now natively generates the document, you can simply attach a UI layer to read this new specification.

To restore Swagger UI in a modern project, install the Swashbuckle.AspNetCore.SwaggerUI package and update your Program.cs:

// Attaching Swagger UI to the Native OpenAPI Specification
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // Generates the spec at /openapi/v1.json
    app.UseSwaggerUI(options => 
    {
        options.SwaggerEndpoint("/openapi/v1.json", "OpenAPI v1");
    });
}

Substitutes for Swagger

1. Scalar

It has emerged as the premier successor to Swagger UI within the .NET community. Following the shift away from Swashbuckle, Scalar has gained traction for its superior aesthetics and modern functionality. As an popular resource on GitHub , Scalar provides an intuitive interface for interacting with RESTful APIs. It offers integrated client code generation for dozens of languages and a streamlined experience for managing headers, cookies, and parameters. Scalar integrates natively with the Microsoft.AspNetCore.OpenApi package, making it a top choice for high-performance, user-friendly documentation.

To integrate Scalar into a .NET 9 Web API, follow these steps to replace legacy Swagger configurations with a native, modern interface.

a. Install the Package

Using the NuGet Package Manager or the CLI, install the Scalar.AspNetCore package.

dotnet add package Scalar.AspNetCore

b. Configure Program.cs

Add the Scalar middleware to the request pipeline. Ensure any remaining Swashbuckle or Swagger references are removed:

if (app.Environment.IsDevelopment())
{
    // Generates the OpenAPI document natively
    app.MapOpenApi(); 
    
    // Mounts the Scalar UI at /scalar/v1
    app.MapScalarApiReference(); 
}

c. Update Launch Settings

Modify launchSettings.json to automatically open the Scalar interface when the application starts by updating the launchUrl property:

"https": {
  "commandName": "Project",
  "dotnetRunMessages": true,
  "launchBrowser": true,
  "launchUrl": "scalar/v1",
  "applicationUrl": "https://localhost:7153;http://localhost:5231",
  "environmentVariables": {
    "ASPNETCORE_ENVIRONMENT": "Development"
  }
}

This configuration leverages native .NET document generation while providing a high-performance, interactive testing environment.

2. Postman

Postman remains a leading platform for API development, offering robust features that streamline testing workflows. A key capability is the direct import of OpenAPI specifications, enabling the rapid generation of request collections. This automation allows for immediate interaction with endpoints, eliminating the need for manual configuration and ensuring testing remains synchronized with the latest API definitions.

To import your .NET API’s OpenAPI specification into Postman, follow these simple steps:

1. Expose the Native OpenAPI Document

Ensure the API is configured to generate the specification natively. In Program.cs, add the following services and middleware:

builder.Services.AddOpenApi();

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

Once the application is running, the raw specification will be accessible at /openapi/v1.json.

2. Import the Specification into Postman

Postman can automatically build request collections from this native endpoint:

  • Open Postman: Select the Import button in the top-left sidebar.

  • Via Link: Choose the Link tab and paste the local URL (e.g., https://localhost:7153/openapi/v1.json).

  • Via File: Alternatively, save the JSON from the browser and drag the file into the Postman import window.

3. Synchronized API Exploration

After the import, Postman generates a structured collection containing all defined routes, schemas, and parameters:

  • Instant Testing: Send requests and view responses immediately without manual setup.

  • Dynamic Configuration: Easily manage authentication tokens, custom headers, and environment variables across the entire collection.

  • Automated Sync: If the API structure changes, re-importing the spec updates the collection, ensuring the testing environment stays current with the code.

Leveraging Postman’s OpenAPI import feature streamlines the testing workflow, simplifying the validation and debugging of .NET APIs. By automating collection creation from native specifications, the process ensures accuracy and reduces the overhead of manual configuration.

Conclusion

In this article, we have seen Microsoft’s strategic transition in .NET 9, moving away from Swashbuckle to a native documentation engine via the Microsoft.AspNetCore.OpenApi package. This shift provides a more sustainable, first-party solution that generates OpenAPI specifications without relying on external dependencies.

We also explored modern alternatives for API testing and visualization. While Swagger UI can still be manually integrated, tools like Scalar offer a more contemporary experience with features like built-in client code generation. Furthermore, we examined how the native OpenAPI output seamlessly connects with Postman to automate the creation of testing collections, ensuring a robust and efficient development workflow.

Hope you enjoyed reading this!

Membership not found