You create a fresh ASP.NET Core Web API.

The application starts correctly.

Your endpoint responds.

Then, almost automatically, you type:

https://localhost:xxxx/swagger

And receive:

404 Not Found

For developers who have worked with ASP.NET Core for years, the immediate reaction is often that Swagger configuration is broken.

It probably is not.

Starting with .NET 9, Microsoft changed the default API documentation architecture. ASP.NET Core now provides first-party OpenAPI generation through Microsoft.AspNetCore.OpenApi, while Swashbuckle is no longer included automatically in the Web API template. Swashbuckle still exists and can still be installed, but it is no longer the template's default solution.

That sounds like a small template change.

Architecturally, however, it reflects a useful separation of concerns.

The Important Change Is Not Really About Swagger

For years, developers commonly used the word Swagger to mean several different things:

• API specification
• generated JSON
• documentation
• browser UI
• interactive testing

Those are separate responsibilities.

.NET 9 makes that separation much harder to ignore.

A modern API documentation stack can be viewed as three layers:

Your ASP.NET Core API
        ↓
OpenAPI document
        ↓
Documentation / testing UI

The UI might be:

Scalar
Swagger UI
NSwag
Redoc
Custom developer portal
API gateway portal

The underlying contract does not have to change.

That distinction is much more important for enterprise systems than deciding whether one interface looks better than another.

OpenAPI Is the Contract

OpenAPI is a language-independent specification describing an HTTP API.

It can describe things such as:

• endpoints,
• HTTP methods,
• parameters,
• request bodies,
• response structures,
• schems,
• authentication schemes,
• status codes.

ASP.NET Core’s first-party OpenAPI support gathers endpoint metadata and converts it into an OpenAPI document.

A basic .NET 9 application can contain:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

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

app.MapControllers();

app.Run();

By default, MapOpenApi() exposes documents under:

/openapi/{documentName}.json

and the standard default document is commonly available at:

/openapi/v1.json

Try opening that URL first.

If the JSON document loads, OpenAPI generation is working.

What you do not automatically have is a graphical documentation application.

Documentation UI Is a Consumer, Not the API Contract

This is the architectural point many teams miss.

Swagger UI does not define your API.

Scalar does not define your API either.

They consume the OpenAPI description.

Think about it like this:

                         ┌── Scalar
                         │
ASP.NET API → OpenAPI ───┼── Swagger UI
                         │
                         ├── Code Generator
                         │
                         ├── API Gateway
                         │
                         └── Developer Portal

Once an organization treats OpenAPI as the central artifact, replacing the visualization layer becomes relatively straightforward.

That gives architecture teams flexibility.

A developer might use Scalar locally.

QA might import the same contract into Postman.

A CI/CD pipeline might validate the document.

An external developer portal might publish it.

A code-generation process might create client SDKs from it.

One contract can support many consumers.

Adding Scalar to a .NET API

Microsoft’s current Minimal API tutorial demonstrates Scalar as one option for rendering the OpenAPI document generated by ASP.NET Core.

Install:

dotnet add package Scalar.AspNetCore

Then add:

using Scalar.AspNetCore;

and configure:

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

With the standard configuration, Microsoft documents the API reference as being available at:

/scalar/v1

and backed by:

/openapi/v1.json

That is an important detail because older examples online sometimes refer simply to /scalar.

Always verify the route against the package version and configuration you are actually using.

Why Scalar Is Interesting for Development Teams

Scalar is not valuable merely because its interface looks more modern.

Its more significant advantage is that API documentation and API interaction are brought closer together.

A developer examining an endpoint can potentially move directly from:

Understand endpoint
        ↓
Inspect schema
        ↓
Configure authentication
        ↓
Send request
        ↓
Inspect response

without switching between multiple tools.

Scalar also supports configuring OpenAPI security schemes and OAuth2 flows, including Authorization Code flows with PKCE.

For example:

app.MapScalarApiReference(options =>
    options
        .AddPreferredSecuritySchemes("OAuth2")
        .AddAuthorizationCodeFlow("OAuth2", flow =>
        {
            flow.ClientId = "developer-client";
            flow.Pkce = Pkce.Sha256;
            flow.SelectedScopes = ["api.read"];
        }));

This becomes useful when working with APIs protected by an identity provider rather than a simple static bearer token.

But Do Not Confuse Convenience With Security

An interactive API reference is extremely convenient.

That does not mean it should automatically be available publicly.

For production fintech APIs, documentation exposure needs the same architectural thinking as any other endpoint.

Consider a payment API exposing operations such as:

POST /payments
POST /payments/{id}/reverse
GET  /accounts/{id}
POST /cards/{id}/block
POST /transfers

Even when authorization protects the underlying transactions, publicly exposing complete schemas and endpoint structures may provide unnecessary reconnaissance information.

ASP.NET Core allows authorization requirements to be applied to the OpenAPI endpoint because it is mapped as a normal route endpoint. Microsoft specifically documents protecting generated OpenAPI documents using authorization policies.

A simple policy could therefore look conceptually like:

app.MapOpenApi()
   .RequireAuthorization("ApiDocumentation");

The same consideration should be given to your documentation UI.

For many systems, the simplest policy is still:

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

Production documentation can then live elsewhere.

A Better Architecture for Fintech APIs

For enterprise APIs, I would avoid treating /scalar or /swagger as the documentation architecture.

Instead, design several layers.

                    ┌────────────────────────────┐
                    │ ASP.NET Core Application   │
                    └─────────────┬──────────────┘
                                  │
                           OpenAPI metadata
                                  │
                    ┌─────────────▼──────────────┐
                    │ OpenAPI Contract           │
                    └─────────────┬──────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
          ▼                       ▼                       ▼
    Developer UI             CI Validation          API Gateway
      Scalar                   / Linting             / Portal
          │                       │                       │
          ▼                       ▼                       ▼
 Local testing            Contract governance      External users

This creates much clearer responsibilities.

The application’s responsibility is to describe itself accurately.

The documentation system’s responsibility is to present that contract.

The gateway’s responsibility is to publish or restrict APIs.

CI/CD’s responsibility is to detect contract problems before production.

OpenAPI Should Become Part of CI/CD

This is where the .NET 9 approach becomes more interesting for architects.

Do not think only about generating OpenAPI at runtime.

Think about using the specification as a build artifact.

For example:

Developer pushes API change
          ↓
Build application
          ↓
Generate OpenAPI document
          ↓
Validate OpenAPI
          ↓
Detect breaking contract changes
          ↓
Security checks
          ↓
Generate SDK
          ↓
Publish documentation
          ↓
Deploy

Microsoft’s OpenAPI tooling also supports generating OpenAPI documents during the build process through Microsoft.Extensions.ApiDescription.Server.

That creates opportunities for governance.

A banking organization could block a release when:

Required response field removed
Authentication definition disappears
Invalid schema introduced
API version changes unexpectedly
PCI-sensitive field appears in response
Breaking contract detected

Now OpenAPI becomes more than documentation.

It becomes part of release control.

Metadata Quality Matters More Than the UI

There is another consequence.

A beautiful Scalar page cannot compensate for poor endpoint metadata.

Suppose your controller says:

[HttpPost]
public IActionResult Process(RequestDto request)
{
    ...
}

The generated document may technically exist, but developers may still have no idea:

• what the operation actually does,
• which status codes are possible,
• whether the operation is idempotent,
• what authentication is required,
• what business validation can fail.

ASP.NET Core can derive OpenAPI information from endpoint metadata, controller attributes and Minimal API constructs such as typed results.

Therefore API design should include meaningful documentation metadata.

For example:

[HttpPost("payments")]
[ProducesResponseType<PaymentResponse>(StatusCodes.Status201Created)]
[ProducesResponseType<ErrorResponse>(StatusCodes.Status400BadRequest)]
[ProducesResponseType<ErrorResponse>(StatusCodes.Status401Unauthorized)]
[ProducesResponseType<ErrorResponse>(StatusCodes.Status409Conflict)]
public async Task<IActionResult> CreatePayment(...)

That provides value regardless of whether the consumer is Scalar, Swagger UI, an SDK generator or an API governance platform.

Do You Need to Remove Swagger?

No.

This change does not mean Swagger UI is obsolete.

Microsoft explicitly states that Swashbuckle remains available as a community package for .NET 9 and later.

If an organization has existing tooling built around Swagger UI, there may be no business reason to migrate immediately.

You can continue using it.

Similarly, NSwag remains another available ecosystem option.

The architectural choice should depend on your requirements rather than template fashion.

Use Swagger UI when existing processes and tooling already depend on it.

Use Scalar when its developer experience and API-client capabilities fit your team.

Use neither publicly if your production documentation belongs in an authenticated developer portal or API-management platform.

The important decision is maintaining a reliable OpenAPI contract underneath all of them.

What I Would Use for a New .NET 9/10 Fintech API

For a greenfield financial API, a practical baseline could be:

ASP.NET Core
    │
    ├── Microsoft.AspNetCore.OpenApi
    │
    ├── OpenAPI transformers
    │
    ├── Scalar for local development
    │
    ├── OAuth2 / OIDC
    │
    └── Production API gateway
             │
             ├── Authentication
             ├── Rate limiting
             ├── Audit
             ├── Developer portal
             └── API analytics

Then establish these rules:

Development

OpenAPI endpoint enabled
Scalar enabled
Developer authentication available

Testing/UAT

OpenAPI restricted
API reference authenticated
Contract validation enabled

Production

OpenAPI either disabled or access controlled
Interactive reference restricted
Published contracts managed through API governance

That is much stronger than simply asking whether Swagger should be enabled.

Conclusion

The disappearance of /swagger from a fresh .NET 9 application is not an API failure.

It represents a cleaner architecture.

Microsoft now provides the OpenAPI generation layer directly, while allowing teams to choose how that contract should be rendered and consumed.

Scalar is an attractive option because it combines readable documentation with interactive API-client capabilities. Swagger UI remains available. NSwag remains available. Other documentation systems can consume the same OpenAPI contract.

But for software architects — especially those building banking, payments, wallet, card, settlement or integration platforms — the larger lesson is more important:

Stop designing API documentation around a UI. Design around the API contract.

Treat OpenAPI as a governed engineering artifact.

Generate it consistently.

Validate it during CI/CD.

Protect it appropriately.

Use it for integration testing.

Use it for SDK generation.

Feed it into your API gateway and developer portal.

Then let Scalar, Swagger UI, or any future renderer become what it should have been all along:

a view over the contract, rather than the contract itself.

I offered you others’ Medium articles: Visit My Profile

Also, my GitHub: Md Hasan Monsur

Connect with me at LinkedIn: Md Hasan Monsur

Swagger Is No Longer in .NET- What API Architects Should Do Instead was originally published in ASP DOTNET on Medium, where people are continuing the conversation by highlighting and responding to this story.

“Check out my stories on Medium! Proud to be a Friend of Medium supporting writers 🌟”

Prerequisites

• .NET 8 SDK installed
• Visual Studio 2022 or your preferred IDE
• Installed IronPDF via NuGet

dotnet new webapi -n IronPdfExample

dotnet add Package IronPdf

Step 1: HTML Template Setup

As with the DinkToPdf version, add an HTML file in a folder named Templates. Templates/ReportTemplate.html (same as before).

Step 2: Create the PDF Generation Service with IronPDF

Create a folder named Services and add a class IronPdfReportService.cs

namespace IronPdfExample.Services
{
    public class IronPdfReportService
    {
        private readonly ChromePdfRenderer _renderer;

        public IronPdfReportService()
        {
            _renderer = new ChromePdfRenderer();
        }

        public byte[] GeneratePdf(string htmlContent)
        {
            using var pdf = _renderer.RenderHtmlAsPdf(htmlContent);
            return pdf.BinaryData;
        }
    }

}

This uses IronPDF’s ChromePdfRenderer, which simulates a full Chromium browser internally, elimiting the need for separate browser installs or external renderers.

Step 3: Register the Service in Program.cs

builder.Services.AddScoped<IronPdfReportService>();

Step 4: Create the Controller

Add an endpoint for IronPDF-based generation in the same ReportController.cs or in a separate controller if preferred:

using IronPdfExample.Services;
using Microsoft.AspNetCore.Mvc;
using IronPdf;

namespace IronPdfExample.Controllers
{
    [ApiController]
    [Route("api/[controller]")]
    public class ReportController : ControllerBase
    {
        private readonly IronPdfReportService _pdfService;

        public ReportController(IronPdfReportService pdfService)
        {
            _pdfService = pdfService;
        }

        [HttpGet("generate-ironpdf")]
        public IActionResult GenerateIronPdfReport()
        {
            var htmlPath = Path.Combine(Directory.GetCurrentDirectory(), "Templates", "ReportTemplate.html");

            if (!System.IO.File.Exists(htmlPath))
                return NotFound("HTML template not found.");

            var htmlContent = System.IO.File.ReadAllText(htmlPath);
            var pdfBytes = _pdfService.GeneratePdf(htmlContent);

            return File(pdfBytes, "application/pdf", "report-ironpdf.pdf");
        }
    }
}

Step 5: Run and Test the Endpoint

Run the Web API:

dotnet run

Then navigate to:

https://localhost:{PORT}/api/report/generate-ironpdf

PDF Output

Why Choose IronPDF?

• No external dependencies (no WkHtmlToPdf library or Webkit)
• Better JavaScript and CSS support via real browser rendering
• Commercial support and active development
• PDF/A, security, watermarking, digital signatures, and more
• Native .NET 8 support with minimal configuration

Conclusion:

Which to Choose?

Both DinkToPdf and IronPDF are capable tools for HTML to PDF conversion, but your choice will depend on your project needs:

IronPDF is a great choice for production-grade solutions where reliability, support, and advanced features are essential.

Try IronPDF for Free : Want to try IronPDF in your project? Download the free trial here.

I offered you others medium article: Visit My Profile

also, My GitHub : Md Hasan Monsur

Connect with me at LinkedIn : Md Hasan Monsur

HTML to PDF Generation using IronPDF in Web API was originally published in ASP DOTNET on Medium, where people are continuing the conversation by highlighting and responding to this story.