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? 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.
The tooling decision is only part of the story - how you configure it to accurately reflect your API's contract matters just as much. Patreon has complete, working configurations with Bearer auth buttons, versioned endpoints, and typed response attributes, ready to drop into your project.
Getting your OpenAPI setup right from day one - [ProducesResponseType] on every action, the correct launchSettings.json for Swagger auto-open, and versioned routes that render cleanly - is exactly what Chapter 1 and Chapter 2 of the ASP.NET Core Web API: Zero to Production course establish as the foundation. Everything built in later chapters depends on getting this part right.
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 webapi in .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.OpenApi package targets OpenAPI 3.1, and the gap matters when you depend on nullable schemas, $ref improvements, or JSON Schema alignment.
Maintenance pace. The core Swashbuckle.AspNetCore repository 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.OpenApi produces - 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 custom IDocumentFilter or IOperationFilter logic from Swashbuckle need to re-express that customization through Microsoft.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 |
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.
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.
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.
About the Author
Celin Daniel is Co-founder of Coding Droplets with 13+ years of hands-on experience building, shipping, and operating .NET and ASP.NET Core systems in production. The guidance here comes from real projects and production incidents, not theory.
