The shape of API docs

If you have shipped a REST or HTTP API in the last decade, you have probably opened a page that looked like an interactive list of endpoints - each one expandable, with parameters, request bodies, response schemas, and a "Try it out" button that fires a real request and prints the response. That page is rendered from a single file: an OpenAPI document describing your API.

Two tools dominate that rendering job. Swagger UI is the original, built by the team that created the spec itself. Scalar is the modern alternative that has taken meaningful ground in the last couple of years, helped along by Microsoft swapping the default API docs experience in ASP.NET Core.

Both read the same input. Both produce broadly the same output - a browsable reference with a built-in HTTP client. They differ in how they look, how they feel, and what they assume about your project.

The spec is the source of truth. The UI is a window onto it.- the OpenAPI design principle

What is Swagger UI?

Swagger UI is an open-source HTML, JavaScript, and CSS bundle that renders an OpenAPI document as interactive API documentation. It is part of the broader Swagger toolset originally built by Reverb Technologies, donated to the OpenAPI Initiative in 2015, and now maintained by SmartBear.

The reason you have seen it so often is that nearly every backend framework ships an integration. FastAPI mounts Swagger UI at /docs by default. NestJS exposes it through @nestjs/swagger. Spring Boot has springdoc-openapi. ASP.NET Core projects have shipped it through Swashbuckle for years. In all of those, you write your API in code, the framework generates an OpenAPI spec, and Swagger UI renders that spec.

What it gives you:

  • Endpoint list grouped by tag, each row expanding into parameters, request body schema, response schemas per status code, and example values.
  • Try it out - an in-page HTTP client that fills in your parameters, sends the request to your real server, and prints the response with headers and timing.
  • Auth flows for OAuth 2, OpenID Connect, API keys, and bearer tokens, with the token persisted across requests inside the page.
  • Schema explorer that walks nested types, enums, discriminators, and references.

The look and feel is recognizable: a pale background, green and blue method badges, a left-flowing list of operations, the schema browser at the bottom. It works. It has been the default for so long that the UI is, for many developers, what an API doc page is.

What is Scalar?

Scalar is an open-source API reference UI built around the same input - an OpenAPI document - and the same goals - browse, try, share. It started as a single React component and now ships as a small library you embed on a page, or a hosted product if you do not want to self-host.

The pitch is essentially three things:

  • A modern UI. Two-pane layout with the operation list on one side and request and response panels on the other. Dark mode by default. Sensible typography. Themable, with a handful of presets and full CSS variable control.
  • A real HTTP client. The "try it out" panel is closer to a Postman-style request builder than Swagger UI's inline form. Code samples in multiple languages (curl, JavaScript, Python, Go, C#) update live as you change the request.
  • Lighter integration. Mount a single endpoint that serves a small script tag and you have docs - no large bundled application to ship inside your API server.

What pushed Scalar from "interesting alternative" to "you have to consider it" was ASP.NET Core 9. The .NET team dropped Swashbuckle from the default web API template - the package that historically bundled Swagger UI - and the docs and templates instead point developers at Microsoft.AspNetCore.OpenApi for spec generation, with Scalar (via Scalar.AspNetCore) as the recommended UI. Overnight, a generation of new .NET API projects started defaulting to Scalar rather than Swagger UI.

The OpenAPI spec underneath

Both tools share the same primary input: an OpenAPI document (JSON or YAML) describing your API. Knowing what that document looks like is most of what you need to understand the picture.

// openapi.json - the truth both UIs render
{
  "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" }
        }
      }
    }
  }
}

In modern backend frameworks, you do not hand-write this file. The framework generates it from your route definitions, types, and annotations. The shape is the contract between three parties:

  • Your backend, which exposes the spec at a known URL.
  • The doc UI (Swagger UI, Scalar, or any of half a dozen others), which reads it and renders.
  • Your clients - SDKs, code generators, test runners, AI agents - which read the same spec to know how to call your API.

Because both Swagger UI and Scalar are just renderers of this spec, the cost of switching between them is small. Your code does not change. Your spec does not change. You swap one middleware line and the other UI appears.

How they compare

The honest comparison is on a handful of specific axes - not "which one is better" in the abstract.

  • Visual design. Scalar's default looks closer to a modern developer tool (dark mode, denser type, two-pane layout). Swagger UI's default looks like a 2017 reference site. Both are themable; the defaults are what most projects ship.
  • Try-it-out experience. Scalar's HTTP client is its calling card - resizable panels, multi-language code samples that update as you edit, a request history. Swagger UI's is inline and minimal: fill in fields, click Execute, read the response below. For exploratory work, Scalar wins; for "just send the request and read the JSON," Swagger UI is fine.
  • Footprint. Swagger UI ships as a sizable bundle - it is a small single-page application. Scalar's mount is lighter (a script tag plus the spec URL). For an internal API on a fast network, neither matters; for a public docs page, Scalar's smaller payload is a real edge.
  • Ecosystem and maturity. Swagger UI has a decade of integrations, plugins, and Stack Overflow answers. Every backend framework still ships a Swagger UI integration as the default or a one-line option. Scalar is younger but already has first-class integrations for .NET, Hono, NestJS, FastAPI, Express, and the major frameworks where it matters.
  • OpenAPI version support. Both handle OpenAPI 3.0 and 3.1. Scalar tends to track newer spec features more aggressively; Swagger UI is conservative and rock-solid on the older versions.
  • Auth. Both support OAuth 2, OpenID Connect, bearer tokens, API keys, and cookies. Swagger UI's auth dialog is the more battle-tested of the two, especially for OAuth 2 redirect flows.

Notably, neither tool generates your OpenAPI document - that is your framework's job. Choosing between them is a presentation decision, not an architectural one.

When to pick which

A reasonable rule of thumb for new projects in 2026:

  • Use Scalar when the docs page is part of your developer-facing product surface - a public API, an SDK landing page, a partner integration site. The modern UI and richer try-it-out are worth the slightly newer ecosystem.
  • Use Swagger UI when the docs are internal, when your framework ships it as the default and you have no reason to change, or when you depend on a Swagger UI plugin (there are many) that has no Scalar equivalent.
  • Use both when you do not want to choose. Because they read the same spec, mounting Swagger UI at /swagger and Scalar at /scalar costs almost nothing. Some teams ship Scalar as the public docs and keep Swagger UI for internal "try it out" work because their team already knows it.

What you should not do is invest engineering time in hand-tuning either UI's themes to the point of fork. Both have configuration knobs; spend a quarter of a day, not a quarter.

Where they fit in the stack

API doc UIs are a small layer sitting on top of a larger pipeline. The full picture for a typical modern backend:

  • Your backend framework (ASP.NET Core, FastAPI, NestJS, Hono, Express, Spring Boot) defines routes and types.
  • A spec generator (Microsoft.AspNetCore.OpenApi, FastAPI's built-in generator, @nestjs/swagger, springdoc-openapi) inspects those routes and produces an OpenAPI document, usually served at /openapi.json or /openapi.yaml.
  • A UI (Swagger UI or Scalar) mounts at a known path, reads the spec, and renders the docs.
  • Downstream consumers read the same spec: SDK generators (openapi-generator, Orval), test runners, mock servers, and increasingly AI agents that need to know how to call your API.

The takeaway is the one that makes API docs in 2026 boring in the best way: write your API, generate the spec, point a UI at it. Whether that UI is Swagger UI or Scalar is a styling decision more than a technology one.

References