Scalar vs Swashbuckle vs NSwag in ASP.NET Core: Which OpenAPI Tool Should Your .NET Team Use in 2026?
If you have been building ASP.NET Core APIs for any length of time, you have almost certainly used Swashbuckle to generate Swagger UI. For years it was the default — bundled right into the dotnet new webapi template. Then .NET 9 dropped it. Microsoft pulled Swashbuckle from the default project template and shipped its own Microsoft.AspNetCore.OpenApi package instead, leaving many teams asking: what do we use now?
🎁 Want implementation-ready .NET source code you can drop straight into your project? Join Coding Droplets on Patreon for exclusive tutorials, premium code samples, and early access to new content. 👉 https://www.patreon.com/CodingDroplets
The OpenAPI tooling landscape in .NET has shifted noticeably in 2026. Scalar has emerged as the modern UI of choice, NSwag continues to serve teams that need full-stack client generation, and Swashbuckle — while still functional — carries the weight of a maintenance question mark. This comparison cuts through the noise, giving you a clear picture of what each tool does, where it excels, and which one belongs in your team's stack.
What Problem Are These Tools Solving?
Before comparing tools, it helps to be precise about the job. OpenAPI tooling in ASP.NET Core does two distinct things that teams often conflate:
- Spec generation — turning your API's routes, request/response models, and annotations into a machine-readable OpenAPI document (JSON or YAML).
- UI rendering — presenting that spec in a human-friendly interface where developers can explore endpoints and test requests.
Some tools do both. Some only do one. Understanding which layer you need to replace changes which tool is the right answer.
With .NET 9 and continuing into .NET 10, Microsoft now handles spec generation natively via Microsoft.AspNetCore.OpenApi. That leaves the UI rendering layer open — and that is where Scalar, Swagger UI (Swashbuckle), and NSwag's built-in UI each compete.
Swashbuckle: The Incumbent Under Pressure
Swashbuckle has been the default ASP.NET Core OpenAPI solution since the early days. It packages Swagger UI and a spec generator (Swashbuckle.AspNetCore) into a single NuGet dependency with a straightforward configuration API.
Why Teams Still Use Swashbuckle
- Familiarity. Most .NET teams have years of Swashbuckle configuration behind them — XML comments, operation filters, security definitions. Switching carries migration cost.
- Rich ecosystem of extensions. There are mature packages for JWT auth UI buttons, versioning filters, and schema customizers built on top of Swashbuckle.
- Controller-centric attribute support. Swashbuckle is particularly well-suited for teams using traditional MVC controllers with
[Produces],[ProducesResponseType], and[ApiExplorer]attributes.
Where Swashbuckle Struggles in 2026
- Dropped from the default template. Microsoft removed Swashbuckle from
dotnet new webapiin .NET 9. This signals a clear directional shift even if the package itself is not deprecated. - OpenAPI version ceiling. Swashbuckle generates OpenAPI 3.0 specs. The new
Microsoft.AspNetCore.OpenApipackage targets OpenAPI 3.1, and the gap matters when you depend on nullable schemas,$refimprovements, or JSON Schema alignment. - Maintenance pace. The core
Swashbuckle.AspNetCorerepository has slowed. New .NET versions require community PRs and sometimes lag behind release cycles — a risk that enterprise teams running upgrade pipelines need to weigh. - No client code generation. Swashbuckle does not generate typed API clients. Teams that need that capability are already reaching for NSwag or Kiota.
Verdict on Swashbuckle: Defensible for teams with significant existing customization and no immediate migration runway. Not the forward-looking default for greenfield projects starting in 2026.
Scalar: The Modern Challenger
Scalar is an open-source API documentation platform with a polished, modern interface. It works as a UI layer on top of any OpenAPI spec — including the one generated by Microsoft.AspNetCore.OpenApi — and integrates into ASP.NET Core via a single NuGet package (Scalar.AspNetCore).
What Makes Scalar Stand Out
- First-class .NET 9/10 integration. Scalar is designed to pair with
Microsoft.AspNetCore.OpenApi. It picked up where Swashbuckle left off in the default template conversation and is now the recommended UI for teams adopting Microsoft's built-in spec generator. - OpenAPI 3.1 compatibility. Because Scalar consumes the spec rather than generating it, it renders whatever
Microsoft.AspNetCore.OpenApiproduces — including OpenAPI 3.1 documents. - Developer experience. The Scalar UI includes themes (light and dark), a built-in search across endpoints, code snippet generation in multiple languages (C#, Python, curl, JavaScript), and a cleaner visual hierarchy than the classic Swagger UI.
- Authentication flows. Scalar handles OAuth2, Bearer tokens, and API keys directly in the UI without requiring custom Swashbuckle filters to inject the lock-button.
- Zero-lock-in. Scalar is just a UI. You own the spec. Switching away from Scalar means removing one package — not rewriting your documentation strategy.
Scalar Limitations to Consider
- Younger ecosystem. Scalar is newer. The extension surface, third-party integrations, and community-contributed filters are thinner than Swashbuckle's.
- No client generation. Like Swashbuckle, Scalar does not generate typed API clients. If your workflow involves generating C# or TypeScript clients from the spec, you still need a separate tool.
- Spec generation still requires
Microsoft.AspNetCore.OpenApi. Scalar solves the UI problem, not the spec-generation problem. Teams using customIDocumentFilterorIOperationFilterlogic from Swashbuckle need to re-express that customization throughMicrosoft.AspNetCore.OpenApi's transformer API.
Verdict on Scalar: The natural choice for teams starting fresh on .NET 9 or .NET 10 who want a modern OpenAPI UI without inheriting Swashbuckle's growing technical debt.
NSwag: The Full-Stack Option
NSwag is a different animal. Where Swashbuckle and Scalar are primarily documentation tools, NSwag is a code generation platform that happens to include spec generation and Swagger UI as features.
What NSwag Brings to the Table
- Typed client generation. NSwag's primary value proposition is generating C# and TypeScript clients directly from your OpenAPI spec. For teams with front-end projects, mobile apps, or service-to-service HTTP clients, this eliminates the manual effort of keeping clients in sync with the API.
- Dual-purpose spec generation and UI. NSwag includes its own spec generator (
NSwag.AspNetCore) and a Swagger UI integration, so it can serve as an all-in-one replacement for Swashbuckle — though most teams use it specifically for the client generation. - MSBuild and CLI integration. NSwag plugs into build pipelines. You can configure it to regenerate TypeScript clients during CI builds, ensuring the client package always reflects the current API surface.
- Standalone and server modes. NSwag Studio (Windows) and the CLI provide spec-generation and client-generation workflows that work outside the ASP.NET Core host — useful for generating clients from third-party APIs.
NSwag Trade-offs
- Complexity tax. NSwag has more moving parts than Swashbuckle or Scalar. Configuration files (
nswag.json), code generation templates, and multi-target setups add cognitive overhead for teams that do not need client generation. - Documentation UI is secondary. The NSwag Swagger UI is functional but not as polished as Scalar. Teams using NSwag primarily for client generation often layer Scalar on top for the documentation experience.
- OpenAPI version gaps. Like Swashbuckle, NSwag's spec generator targets OpenAPI 3.0. Teams relying on .NET 10's native spec generator can use NSwag solely for its client-generation CLI against the output spec, which is a valid split approach.
Verdict on NSwag: The right choice when your team generates typed API clients as part of the development workflow. Not a better Swashbuckle replacement for pure documentation — it solves a different, broader problem.
Side-by-Side Comparison
| Capability | Swashbuckle | Scalar | NSwag |
|---|---|---|---|
| Spec generation | ✅ (OpenAPI 3.0) | ❌ (relies on host) | ✅ (OpenAPI 3.0) |
| UI rendering | ✅ Swagger UI | ✅ Modern UI | ✅ Swagger UI |
| OpenAPI 3.1 support | ❌ | ✅ (consumes native spec) | ❌ |
| Typed client generation | ❌ | ❌ | ✅ C# + TypeScript |
| .NET 9/10 template default | ❌ Removed | ✅ Recommended pairing | ❌ |
| Extension ecosystem maturity | ✅ Extensive | 🔶 Growing | ✅ Established |
| UI quality | 🔶 Functional | ✅ Modern, polished | 🔶 Functional |
| CI/build pipeline integration | ❌ | ❌ | ✅ MSBuild + CLI |
| Setup complexity | Low | Low | Medium-High |
Which Tool Should Your Team Choose?
Choose Scalar + Microsoft.AspNetCore.OpenApi When:
- You are starting a new ASP.NET Core project on .NET 9 or .NET 10
- You want a modern, polished documentation experience with minimal friction
- You do not need typed client generation
- You want to stay aligned with Microsoft's default direction
- OpenAPI 3.1 compatibility matters for your toolchain
Stick with Swashbuckle When:
- You have a mature, heavily customized Swashbuckle setup with significant operation filter logic
- Your team is mid-upgrade-cycle and migration cost outweighs modernization benefit
- Your project still targets .NET 8 or earlier where Swashbuckle remains the default
- You rely on specific community packages that are Swashbuckle-specific
Choose NSwag When:
- Your team generates typed C# or TypeScript clients from the API spec as part of your development workflow
- You maintain front-end apps or mobile clients that consume your ASP.NET Core APIs
- You want to automate client regeneration in CI/CD pipelines
- Consider pairing NSwag client generation with Scalar UI for the best of both — NSwag for clients, Scalar for documentation
Is There a Migration Path from Swashbuckle to Scalar?
Yes, and it is not as painful as it might seem. The general migration path for teams moving from Swashbuckle to Microsoft.AspNetCore.OpenApi + Scalar involves three steps:
First, add Microsoft.AspNetCore.OpenApi to your project and configure it using the AddOpenApi() and MapOpenApi() registration pattern. This replaces Swashbuckle's spec generation.
Second, add Scalar.AspNetCore and register the UI middleware via MapScalarApiReference(). This replaces Swagger UI.
Third, re-express your Swashbuckle customizations — operation filters, security definitions, XML comment integration — using Microsoft.AspNetCore.OpenApi's document and operation transformers. The concepts are the same; the API surface differs.
For most APIs, the migration can be completed in a single focused sprint. Complex customizations — especially around authentication UI flows or custom schema generation — may require additional investigation against the official Microsoft OpenAPI documentation.
What About NSwag Client Generation with the New Stack?
NSwag client generation works perfectly against specs produced by Microsoft.AspNetCore.OpenApi. The workflow is: .NET 10 API generates the spec at /openapi/v1.json, your NSwag configuration file points at that endpoint, and your build pipeline regenerates the typed client on each run.
This means you do not have to choose between the new default stack and NSwag's client generation capability. You can run Microsoft.AspNetCore.OpenApi for spec generation, Scalar for documentation UI, and NSwag CLI for typed client generation — each tool doing only what it does best.
☕ Prefer a one-time tip? Buy us a coffee — every bit helps keep the content coming!
FAQ
Why Did Microsoft Remove Swashbuckle from the Default ASP.NET Core Template?
Microsoft removed Swashbuckle from the dotnet new webapi template in .NET 9 because it was shipping a third-party package as a first-class default — a dependency Microsoft neither owned nor controlled. Shipping their own Microsoft.AspNetCore.OpenApi package gives the team direct ownership of OpenAPI spec generation as a supported platform feature, rather than depending on a community-maintained library for a fundamental capability.
Can I Still Use Swashbuckle with .NET 10?
Yes. Swashbuckle is not deprecated — it was removed from the default template, which is different. You can add Swashbuckle.AspNetCore to any .NET 10 project and it will work. The question is whether the maintenance trajectory and OpenAPI 3.0 ceiling align with your team's needs over the next 2-3 years.
Does Scalar Replace Swagger UI Completely?
Scalar replaces Swagger UI as the rendered documentation interface, but Scalar itself does not generate the OpenAPI spec. In the new default stack, Microsoft.AspNetCore.OpenApi handles spec generation and Scalar renders it. If you removed both Swashbuckle and added Scalar without also configuring Microsoft.AspNetCore.OpenApi, you would have a UI with no spec to display.
Does NSwag Support OpenAPI 3.1?
NSwag's built-in spec generator targets OpenAPI 3.0. However, NSwag's client generation tooling can consume OpenAPI 3.1 specs produced by Microsoft.AspNetCore.OpenApi for client code generation purposes. Check the NSwag GitHub repository for the latest compatibility status on 3.1 generation support.
Which Tool Is Best for Teams Using Minimal APIs?
Scalar paired with Microsoft.AspNetCore.OpenApi is the recommended approach for Minimal API projects. The native spec generator integrates cleanly with the endpoint routing model, and Scalar renders the output without friction. Swashbuckle works with Minimal APIs but requires additional configuration compared to controller-based projects.
Is Scalar Free to Use?
Yes, Scalar.AspNetCore is open-source and free under the MIT license. Scalar also has a cloud platform for hosted documentation, but the ASP.NET Core integration package is entirely free for self-hosted use.
How Do I Handle Authentication in Scalar Compared to Swashbuckle?
Scalar has built-in support for Bearer token, API key, and OAuth2 authentication flows directly in the UI. In Swashbuckle, you typically needed to add a SecurityDefinition and SecurityRequirement operation filter. Scalar handles this through the Authentication configuration in MapScalarApiReference, making the setup more declarative and less code-heavy.
