What is Scalar?

Scalar is an open-source API reference tool. You point it at an OpenAPI document and it renders an interactive documentation page - a browsable list of endpoints, request and response schemas, an in-page HTTP client, and code samples in the language of your choice. It is, in shape, the same job Swagger UI has done for the last decade. What Scalar changes is how the result looks and feels.

The project is maintained by Scalar (the company), released under the MIT license, and developed in the open at github.com/scalar/scalar. It ships as a small library you embed in a page, as a single script tag for the no-build case, and as integration packages for the major backend frameworks - ASP.NET Core, NestJS, Express, Hono, FastAPI, Fastify, and others.

Scalar is what API docs look like when you build them after a decade of learning what works.- the design pitch, in one sentence

The OpenAPI input

Scalar is a renderer. The thing it renders is an OpenAPI document - a JSON or YAML file that describes your API's endpoints, parameters, request bodies, response schemas, authentication, and metadata. Modern backend frameworks generate this file for you from your route definitions and types.

// openapi.json - the input Scalar reads
{
  "openapi": "3.1.0",
  "info": { "title": "StackNova API", "version": "1.0.0" },
  "paths": {
    "/articles/{slug}": {
      "get": {
        "summary": "Fetch an article",
        "parameters": [
          { "name": "slug", "in": "path", "required": true }
        ],
        "responses": { "200": { "description": "The article" } }
      }
    }
  }
}

Scalar supports OpenAPI 3.0 and 3.1, plus legacy Swagger 2.0 specs. Because it is purely a renderer of a standard format, switching from another doc UI to Scalar (or back) does not require any change to your API code - only to the middleware that mounts the docs page.

What it gives you

Scalar's surface is small and considered. The defining pieces:

  • Two-pane layout. The endpoint list and section navigation sit on the left; the selected operation, with its parameters, examples, request body, and response, fills the right. The pattern is closer to a modern developer tool than to a classic docs page.
  • Built-in HTTP client. Each operation has a request panel where you fill in parameters, headers, and a body, then send a real request to your server. The response - status, headers, body, timing - is rendered inline. The experience is closer to Postman or Insomnia than to Swagger UI's inline "Try it out" form.
  • Multi-language code samples. The same request you are building is shown as ready-to-paste code in curl, JavaScript (fetch), Python (requests), Go, C#, PHP, and a handful of others. Edit a parameter; every sample updates.
  • Authentication flows. OAuth 2 (including PKCE), OpenID Connect, bearer tokens, API keys, and basic auth are all first-class, with tokens persisted across requests in the page.
  • Theming. Several presets ship out of the box (default, Kepler, Mars, Saturn, and others), and a small set of CSS variables takes you the rest of the way to a custom look. Dark mode is the default.
  • Search. Built-in fuzzy search across endpoints, schemas, and tags. Cmd-K from anywhere.

What Scalar deliberately does not do: generate your OpenAPI document. That is your framework's job, and there are mature spec generators for every major backend.

How to mount it

Three common shapes, depending on how much your project wants Scalar baked in.

1. As a script tag - the zero-build case. Drop two lines into any HTML page and you have docs:

<script id="api-reference" data-url="/openapi.json"></script>
<script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>

2. As a backend middleware - one line in your server wires it up at a known route. For ASP.NET Core 9:

// Program.cs
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenApi();

var app = builder.Build();
app.MapOpenApi();          // serves /openapi/v1.json
app.MapScalarApiReference(); // serves /scalar/v1 (the UI)

app.Run();

3. As a React component - if your docs page is part of a larger frontend, import the component directly:

import { ApiReferenceReact } from "@scalar/api-reference-react";

export default function Docs() {
  return <ApiReferenceReact configuration={{ url: "/openapi.json" }} />;
}

All three shapes read the same OpenAPI spec and produce the same UI. The choice is purely about how you want the docs page to be served.

The ASP.NET Core 9 moment

For most of 2024 and into 2025, Scalar was a credible alternative to Swagger UI but not yet the obvious one. That changed when the .NET team shipped ASP.NET Core 9 and made a quiet but consequential decision: the default web API template stopped bundling Swashbuckle - the package that historically pulled in Swagger UI - and moved spec generation to the new Microsoft.AspNetCore.OpenApi package instead.

With Swashbuckle out of the default template, .NET projects need a UI to mount on top of the spec. The official ASP.NET Core docs and templates recommend Scalar.AspNetCore. The package adds a single line - app.MapScalarApiReference() - and the docs page is live at /scalar/v1. The result: a generation of new .NET API projects in 2025 and 2026 default to Scalar rather than Swagger UI without anyone explicitly choosing.

Outside the .NET ecosystem, Scalar's adoption is more "the team chose it" than "the framework chose it for them," but the trajectory is steady.

Where it fits in the stack

Scalar is one layer of a longer pipeline. Read from your code outward:

  • Your backend framework (ASP.NET Core, FastAPI, NestJS, Hono, Express, Spring Boot) defines routes and types.
  • A spec generator built into that framework (or a package like Microsoft.AspNetCore.OpenApi) produces an OpenAPI document, usually served at /openapi.json.
  • Scalar reads that spec and renders the docs UI.
  • Downstream consumers - SDK generators, test runners, mock servers, AI agents - read the same spec to know how to call your API.

Two things to notice. First, Scalar is genuinely a small piece - swapping it out for another renderer costs you a middleware line, not a refactor. Second, it benefits from work that already needed to happen: if your framework generates OpenAPI well, Scalar's output looks great with no extra effort.

When to pick Scalar

A reasonable shortlist of when Scalar is the right call:

  • You are starting a new ASP.NET Core 9 (or later) project. The path of least resistance is also the documented one - add Scalar.AspNetCore and move on.
  • Your docs page is part of your product surface. If developers outside your team will see the page - public API, SDK landing site, partner integration - the modern UI and built-in client are worth the move.
  • You want a lighter payload. Scalar's mounted page is meaningfully smaller than Swagger UI's bundled single-page app.
  • You want strong defaults with light theming. Scalar's presets and CSS-variable theming get you to a custom look in an afternoon, not a sprint.

Cases where Scalar may not be the right call: legacy projects already deeply invested in Swagger UI plugins, internal-only APIs where the existing docs are fine, or teams that depend on a Swagger UI feature without a Scalar equivalent. Both tools read the same spec, so you can also mount them side by side and pick later.

For the head-to-head against the established default, read Swagger UI and Scalar - the side-by-side piece.

References