How .NET 9 and Scalar solve the problem of under-documented APIs

.NET 9 🤝 Scalar

Mar 05, 2025

Stop me if you’ve heard this one before:

You finish and ship a change to your API.
You don’t bother to document it.
You forget to generate and/or update the API docs.
You definitely don’t publish the newly updated API docs so others can actually use it.

This under-documentation means fewer people being able to use the API, more confusion when you return to this code, and makes it trickier to debug if issues occur.

We don’t blame you for under-documenting your API. In many codebases, the documentation is disconnected from the actual code. This creates needless work in the process of documenting, updating, and publishing API docs.

With the release of .NET 9 in combination with Scalar, we are changing this.

What’s changed with the .NET 9 release?

The `ASP.NET` ecosystem used to have a solution for working with APIs documents in Swashbuckle. This generated API documentation and a UI for your ASP.NET Core API and was a solution to the under-documented problem.

The big problem is that Swashbuckle has not kept up with .NET releases. There was not an official release for .NET 8 and has otherwise seemingly been abandoned. No PRs have been merged since November 2022.

To fix this gap, the ASP.NET Core team is removing Swashbuckle with the release of .NET 9 and replacing it with their own solution for OpenAPI document generation.

What this looks like is built-in support for OpenAPI document generation via the Microsoft.AspNetCore.OpenApi and Microsoft.Extensions.ApiDescription.Server packages. This generates a JSON OpenAPI document automatically based on a map of the API.

For example, after installing both packages, add builder.Services.AddOpenApi(); and app.MapOpenApi(); to your Program.cs file:

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();

app.MapGet("/", () => "Hello world!");

app.Run();

Running this then generates an OpenAPI document at https://localhost:<port>/openapi/v1.json.

Generating this is document is a great first step, but is only part of the solution. It then needs to be turned into documentation people can use. This is where Scalar’s suite of API tools come in.

Setting up Scalar’s ASP.NET package

Thanks to @captainsafia and @xC0dex of our community, Scalar has a ASP.NET API package.

To set it up, simply install the package:

dotnet add package Scalar.AspNetCore

And add the directive and MapScalarApiReference() to your program:

using Scalar.AspNetCore;

var builder = WebApplication.CreateBuilder();

builder.Services.AddOpenApi();

var app = builder.Build();

app.MapOpenApi();
app.MapScalarApiReference();

app.MapGet("/", () => "Hello world!");

app.Run();

Like magic, this gives you a full set of API docs when you navigate to https://localhost:<port>/scalar/v1 in your browser.

Under the hood of how Scalar generates your API docs

You might be asking “how did that happen so quickly?” Well, when you add and run Scalar in your ASP.NET API, we do the following:

Configure Scalar options including the location of your OpenAPI document and any customizations you want like titles, themes, and authentication
Map a GET endpoint to your API that serves a page.
On that page, use your OpenAPI document and Scalar configuration to load your version of Scalar’s API docs from a CDN.

This creates a complete set of API docs in a simple to use UI without all of the work of building it. For further customization, you can create an account and edit your docs however you like.

Solving the under-documented API problem

The combination of new ASP.NET OpenAPI generation and Scalar solves the undocumented API problem. No more needing to document, generate, update, and serve your API docs.

We don’t stop there either. Our API seamlessly turn into a fully featured API client. This means you not only get to document your API but test it. This is a core part of our aim of creating a world-class developer experience for your APIs.

Scalar