Scalar Blog

OpenAPI with NestJS

Tue, 13 Oct 2026 00:00:00 GMT

NestJS generates an OpenAPI document from your controllers and DTOs through the official @nestjs/swagger package. Add it, build a document in main.ts, and the JSON is served next to your API. Like most code-first generators, the setup takes five minutes and the accuracy takes longer, because TypeScript types disappear at runtime and Nest can only document what it can see.

This is part one of a three-part series, and it is vendor-neutral. Everything here is standard NestJS and works the same whichever documentation UI, SDK generator or linter reads the result. Part two covers what you can build from the document, and part three walks through one concrete setup.

The package is called @nestjs/swagger for historical reasons. What it produces is an OpenAPI document; "Swagger" survives in the name and in the bundled Swagger UI. Behaviour below matches the NestJS OpenAPI documentation and the nestjs/swagger source as of September 2026.

Install and bootstrap

shell

npm install --save @nestjs/swagger

If you use the Fastify adapter, also install @fastify/static.

Then build the document in main.ts:

import { NestFactory } from '@nestjs/core'
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
import { AppModule } from './app.module'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)

  const config = new DocumentBuilder()
    .setTitle('Bookstore API')
    .setDescription('Books, authors and orders.')
    .setVersion('1.0.0')
    .addTag('books')
    .build()

  const documentFactory = () => SwaggerModule.createDocument(app, config)
  SwaggerModule.setup('api', app, documentFactory)

  await app.listen(3000)
}
bootstrap()

Passing a factory instead of a finished document is the current recommended form: Nest builds the document on the first request, not during startup.

With that in place:

URL	What it is
`/api`	Swagger UI
`/api-json`	The OpenAPI document as JSON
`/api-yaml`	The same document as YAML

All three are configurable through the fourth argument to setup(), which takes options such as jsonDocumentUrl, yamlDocumentUrl, ui (set it to false to serve only the document) and raw (choose which formats are exposed). useGlobalPrefix: true puts them under your global prefix.

Which OpenAPI version you get

The document declares openapi: 3.0.0 by default; that is the base document in the package source. DocumentBuilder.setOpenAPIVersion('3.1.0') changes the declared version. Changing the number does not by itself rewrite schemas into 3.1 style, so if you declare a newer version, run the output through a validator for that version before you rely on it. Recent releases of the package have started to add newer features, such as hierarchical tags through addTag(); check the operations page for what your installed version supports.

For most teams, a correct 3.0 document is a fine starting point. Every documentation UI and SDK generator you are likely to use reads it. Our OpenAPI 3.1 vs 3.0 guide explains what you gain by moving.

Why DTOs need help

Here is the core problem. This controller looks fully typed:

@Controller('books')
export class BooksController {
  @Get(':id')
  findOne(@Param('id') id: string): Promise<Book> {
    return this.booksService.findOne(id)
  }
}

But TypeScript interfaces and type annotations are erased at compile time. At runtime, Nest can see that there is a GET /books/:id route with an id path parameter, and it can read the class metadata TypeScript emits for decorated members. It cannot see that the method returns a Book, and it cannot see which properties Book has unless something records them.

There are two ways to record them: decorators you write by hand, or the CLI plugin that writes them for you at compile time. You will likely use both.

Decorators by hand

import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger'

export class Book {
  @ApiProperty({ description: 'Unique identifier', example: 'bk_123' })
  id: string

  @ApiProperty({ maxLength: 200, example: 'Dune' })
  title: string

  @ApiPropertyOptional({ example: 'Book one' })
  subtitle?: string
}

DTOs must be classes, not interfaces or type aliases, for any of this to work.

The CLI plugin

The Swagger CLI plugin is a TypeScript transformer that reads your types during compilation and adds the metadata for you. Enable it in nest-cli.json:

json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@nestjs/swagger",
        "options": {
          "classValidatorShim": true,
          "introspectComments": true
        }
      }
    ]
  }
}

With the plugin on, every property in a file ending in .dto.ts or .entity.ts is documented as if it had @ApiProperty(), including whether it is optional, its type, and its default value. classValidatorShim turns class-validator decorators such as @MaxLength(200) into schema constraints. introspectComments turns JSDoc comments on properties into descriptions and examples, so you do not write every description twice.

Two things trip people up:

File naming. The plugin only processes files matching dtoFileNameSuffix (default ['.dto.ts', '.entity.ts']) and controllerFileNameSuffix (default ['.controller.ts']). A DTO in book.ts is silently skipped. Rename it or change the option.
Other builders. The plugin runs as part of the Nest CLI's TypeScript compilation. With SWC, the docs recommend nest start -b swc --type-check, and monorepos need a metadata generation step plus SwaggerModule.loadPluginMetadata(). With other build tools, check the plugin page before assuming it ran.

Describe responses explicitly

Even with the plugin, Nest does not know what a handler returns. Say so:

import {
  ApiNotFoundResponse,
  ApiOkResponse,
  ApiOperation,
  ApiTags,
} from '@nestjs/swagger'

@ApiTags('books')
@Controller('books')
export class BooksController {
  @Get(':id')
  @ApiOperation({ summary: 'Get a book' })
  @ApiOkResponse({ type: Book, description: 'The requested book' })
  @ApiNotFoundResponse({ description: 'No book with that ID' })
  findOne(@Param('id') id: string): Promise<Book> {
    return this.booksService.findOne(id)
  }
}

There is a shorthand decorator for every common status (@ApiCreatedResponse, @ApiForbiddenResponse, and so on), all built on @ApiResponse({ status, ... }). For arrays, use @ApiOkResponse({ type: Book, isArray: true }) or type: [Book].

This is the most common gap in NestJS documents: the happy path is documented, and the 404 thrown by NotFoundException in the service is not. Every tool downstream then believes the endpoint cannot fail.

Make operation IDs stable

Each operation gets an operationId. By default @nestjs/swagger builds it as {ControllerName}_{methodName}, so the handler above becomes BooksController_findOne. That is unique and stable as long as you do not rename classes, but it is not what you want as a method name in a generated SDK.

SDK generators name methods after operation IDs, and renaming one later is a breaking change for anyone using the client. Decide the scheme now with operationIdFactory:

const documentFactory = () =>
  SwaggerModule.createDocument(app, config, {
    operationIdFactory: (controllerKey: string, methodKey: string) => methodKey,
  })

Using only methodKey requires method names to be unique across controllers. If they are not (every controller has a findOne), keep the controller in the ID but drop the Controller suffix, or set IDs per route with @ApiOperation({ operationId: 'getBook' }).

Authentication

Declare the security schemes on the document, then attach them to controllers or handlers:

const config = new DocumentBuilder()
  .setTitle('Bookstore API')
  .setVersion('1.0.0')
  .addBearerAuth()
  .addApiKey({ type: 'apiKey', name: 'X-API-Key', in: 'header' }, 'api-key')
  .build()

@ApiBearerAuth()
@Controller('orders')
export class OrdersController {}

Your guards still enforce authentication at runtime. The decorators only describe it, and Nest does not check that the two agree. When they drift, documentation UIs show the wrong auth form and generated clients ask for the wrong credentials. A test that compares guarded routes with the document's security requirements is worth writing if you have many of them.

Mapped types: import from the right package

Nest's mapped types (PartialType, PickType, OmitType, IntersectionType) are how most apps derive update and create DTOs:

import { PartialType } from '@nestjs/swagger'

export class UpdateBookDto extends PartialType(CreateBookDto) {}

Import them from @nestjs/swagger, not from @nestjs/mapped-types. Both work at runtime, but only the @nestjs/swagger versions carry the OpenAPI metadata across, so the other import produces an update DTO with no properties in the document. It is the single most common "why is my schema empty" answer.

Enums, generics and extra models

Enums. Give them a name so they become a reusable schema instead of an inline list repeated everywhere:

@ApiProperty({ enum: BookFormat, enumName: 'BookFormat' })
format: BookFormat

Generic responses. TypeScript generics are erased, so a Paginated<Book> wrapper cannot be discovered. Register the inner model with @ApiExtraModels(Book) and compose the response with allOf and getSchemaPath(Book). The operations page has a complete example, including a reusable ApiPaginatedResponse decorator. Wrap it once and reuse it.

Hiding things. @ApiExcludeEndpoint() and @ApiExcludeController() remove routes from the document. @ApiHideProperty() removes a property, which you need when the CLI plugin would otherwise document an internal field.

Export the document for CI

The served document is fine for development. For CI you want a file: something you can lint, diff against the last release, commit, and hand to other tools. The simplest approach is a small script that builds the app without listening:

// scripts/export-openapi.ts
import { writeFileSync } from 'node:fs'
import { NestFactory } from '@nestjs/core'
import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger'
import { AppModule } from '../src/app.module'

async function main() {
  const app = await NestFactory.create(AppModule, { logger: false })
  const config = new DocumentBuilder().setTitle('Bookstore API').setVersion('1.0.0').build()
  const document = SwaggerModule.createDocument(app, config)
  writeFileSync('openapi.json', JSON.stringify(document, null, 2))
  await app.close()
}
main()

Keep the DocumentBuilder configuration in one shared function so main.ts and this script cannot drift. If your modules connect to a database on startup, you will need to stub those providers or use a test module here. Then lint the file in CI (our Spectral rules guide has a starting ruleset) and compare it with the previous release to catch breaking changes.

Common mistakes

Interfaces as DTOs. They vanish at runtime. Use classes.
DTO files without the .dto.ts suffix when relying on the CLI plugin.
Mapped types from @nestjs/mapped-types. The derived DTO shows up empty.
No response decorators. Return types are invisible to Nest, so the document has no response schema.
Default operation IDs in a public SDK. BooksController_findOne becomes a method name.
Auth decorators that disagree with guards. Nothing checks them against each other.

What to do with the document

Now you have an accurate OpenAPI document coming out of your app and your CI. The value is in what reads it:

A documentation UI. @nestjs/swagger serves Swagger UI. Set ui: false and you can serve any other UI that reads OpenAPI from the same JSON route.
Client SDKs for the languages your users write, generated from the document instead of maintained by hand.
An MCP server so AI agents can call the operations you choose.
Contract tests and breaking-change checks against the last published document.

Part two of this series covers each of those. If you want the short version today, the NestJS API documentation page shows the setup, and the NestJS integration guide lists every option.

Frequently asked questions

Where is the NestJS OpenAPI JSON document?

If you call SwaggerModule.setup('api', ...), the JSON is at /api-json and YAML at /api-yaml. Change them with the jsonDocumentUrl and yamlDocumentUrl options.

Is @nestjs/swagger OpenAPI or Swagger?

It generates an OpenAPI 3.x document. The package name and the bundled Swagger UI keep the older "Swagger" name.

Why are my NestJS DTO properties missing from the schema?

Usually one of three things: the DTO is an interface rather than a class, the file does not end in .dto.ts or .entity.ts while you rely on the CLI plugin, or a mapped type was imported from @nestjs/mapped-types instead of @nestjs/swagger.

How do I change operation IDs in NestJS?

Pass operationIdFactory in the options to SwaggerModule.createDocument, or set operationId in @ApiOperation() on a single handler.

Can I serve the OpenAPI document without Swagger UI?

Yes. Pass { ui: false } as the options to SwaggerModule.setup and only the document routes are served.

Which OpenAPI version does NestJS generate?

The document declares OpenAPI 3.0.0 by default. DocumentBuilder.setOpenAPIVersion() changes the declared version; validate the output against that version before relying on it.

Learn: What is OpenAPI? · OpenAPI vs Swagger
Docs: NestJS integration guide
Product: NestJS API documentation — turn the document from this post into interactive docs with one package

OpenAPI with FastAPI

Thu, 08 Oct 2026 00:00:00 GMT

FastAPI generates an OpenAPI document for your API automatically, from the type hints, Pydantic models and decorators you already write. Start any FastAPI app and the document is at /openapi.json. The interesting work is not turning it on. It is making the document accurate enough that other tools can rely on it.

This is part one of a three-part series and it is vendor-neutral. Everything below is plain FastAPI and Pydantic, and it applies whatever you later point at the document: a documentation UI, an SDK generator, a linter, or a contract test. Part two covers what you can build from the document, and part three walks through one concrete setup.

Behaviour described here matches the FastAPI documentation and release notes as of September 2026, when the latest release was 0.141.1.

How FastAPI builds the document

FastAPI walks every route registered on the app, and for each one it collects:

the path, the HTTP method, and path, query, header and cookie parameters from the function signature,
the request body schema from Pydantic models,
the response schema from the return type annotation or response_model,
any metadata you pass to the decorator (summary, tags, responses, and so on).

Pydantic produces JSON Schema for every model, and FastAPI assembles those schemas into components.schemas with the paths around them. The result is generated on the first request to /openapi.json and cached on app.openapi_schema.

Since FastAPI 0.99.0, the output is OpenAPI 3.1.0, which means schemas are JSON Schema 2020-12. Nullable fields come out as anyOf with a null type rather than the 3.0-only nullable: true. That is correct and matches what Pydantic v2 produces natively, but it catches people who feed the document to a tool that only reads 3.0. More on that below.

The minimum app

python

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI(title="Bookstore API", version="1.0.0")


class Book(BaseModel):
    id: int
    title: str
    subtitle: str | None = None


@app.get("/books/{book_id}")
def get_book(book_id: int) -> Book:
    return Book(id=book_id, title="Dune")

Run it with fastapi dev main.py and you get three URLs:

URL	What it is	Controlled by
`/openapi.json`	The OpenAPI document	`openapi_url`
`/docs`	Swagger UI	`docs_url`
`/redoc`	ReDoc	`redoc_url`

Set any of them to None to turn it off. Setting openapi_url=None disables the document and both UIs, because the UIs read from it.

Describe the API, not only the types

A document generated from types alone is valid but thin. Here is what to add, ordered by how much it helps the people and tools that read it.

App-level metadata

python

app = FastAPI(
    title="Bookstore API",
    version="1.0.0",
    summary="Books, authors and orders.",
    description="Use this API to manage the catalogue and place orders.",
    contact={"name": "API team", "email": "api@example.com"},
    license_info={"name": "MIT", "identifier": "MIT"},
    openapi_tags=[
        {"name": "books", "description": "Browse and manage the catalogue."},
        {"name": "orders", "description": "Place and track orders."},
    ],
)

openapi_tags sets the order and description of tag groups. Documentation UIs use it for navigation, and several SDK generators use tags to group methods into namespaces. description accepts Markdown.

Per-operation metadata

python

@app.get(
    "/books/{book_id}",
    tags=["books"],
    summary="Get a book",
    response_description="The requested book",
    responses={404: {"description": "Book not found"}},
)
def get_book(book_id: int) -> Book:
    """
    Returns a single book by ID.

    Books that have been removed from the catalogue return **404**.
    """
    ...

The docstring becomes the operation description, and Markdown in it is preserved. summary defaults to a title-cased version of the function name, which is fine for get_book and less fine for handle_v2_lookup.

Document every response, not only the happy path

This is the most common gap in FastAPI documents. FastAPI knows the success response from your return type, and it adds a 422 validation error response to every operation that takes parameters or a body. It does not know about the 404 you raise with HTTPException inside the function, because that happens at runtime.

Declare those with responses, and give them a model when the body has a shape:

python

class ErrorMessage(BaseModel):
    detail: str


@app.get(
    "/books/{book_id}",
    responses={404: {"model": ErrorMessage, "description": "Book not found"}},
)
def get_book(book_id: int) -> Book:
    ...

If most of your endpoints share error responses, define the dictionary once and merge it in: responses={**common_errors, 404: {...}}.

Parameters and fields

Use Annotated with Path, Query, Header and Pydantic's Field to add descriptions, constraints and examples. Constraints become schema keywords that validators and generated clients understand:

python

from typing import Annotated
from fastapi import Path, Query
from pydantic import Field


class Book(BaseModel):
    id: int = Field(description="Unique identifier")
    title: str = Field(max_length=200, examples=["Dune"])
    subtitle: str | None = Field(default=None, examples=["Book one"])


@app.get("/books")
def list_books(
    limit: Annotated[int, Query(ge=1, le=100, description="Page size")] = 20,
    cursor: Annotated[str | None, Query(description="Cursor from the previous page")] = None,
) -> list[Book]:
    ...

Examples in Pydantic Field(examples=[...]) go into the JSON Schema. If you want OpenAPI's named examples on a request body (several labelled examples that a UI can switch between), use Body(openapi_examples={...}) instead.

Make operation IDs stable

Every operation in the document has an operationId. FastAPI generates it from the function name, the path and the method, so get_book on GET /books/{book_id} becomes something like get_book_books__book_id__get. That is unique, which is what the spec requires, but it is not pleasant, and it changes if you rename the function or move the path.

It matters because SDK generators name methods after operation IDs. An unstable ID is an unstable SDK method name, which is a breaking change for anybody using a generated client. FastAPI's own SDK generation guide recommends a custom generate_unique_id_function:

python

from fastapi import FastAPI
from fastapi.routing import APIRoute


def custom_generate_unique_id(route: APIRoute) -> str:
    return f"{route.tags[0]}-{route.name}"


app = FastAPI(generate_unique_id_function=custom_generate_unique_id)

That gives you books-get_book, and it only changes when you rename the function or its tag on purpose. Note that this example assumes every route has at least one tag; add a fallback if yours do not. You can also pass operation_id="getBook" to a single decorator.

Authentication

FastAPI's security utilities are dependencies that also register security schemes in the document. Use them rather than reading headers by hand, and the document describes your auth correctly for free:

python

from fastapi import Depends
from fastapi.security import APIKeyHeader, HTTPBearer

api_key = APIKeyHeader(name="X-API-Key")
bearer = HTTPBearer()


@app.get("/orders")
def list_orders(key: str = Depends(api_key)) -> list[Order]:
    ...

This adds an apiKey scheme to components.securitySchemes and a security requirement to the operation. OAuth2PasswordBearer(tokenUrl="token") does the same for the OAuth 2.0 password flow. Documentation UIs read these to show an authentication form, and SDK generators read them to decide what the client constructor asks for.

If you read request.headers["Authorization"] directly instead, the endpoint works but the document says it is unauthenticated, and every tool downstream believes it.

Input and output schemas

Since FastAPI 0.102.0, a model used for both requests and responses can produce two schemas, Book-Input and Book-Output. The reason is honest: a field with a default is optional when you send it, but always present when the server returns it. Two schemas describe that precisely.

If your consumers find the split confusing, or a generator produces awkward type names from it, turn it off:

python

app = FastAPI(separate_input_output_schemas=False)

You get a single Book schema, and fields with defaults are not marked as required. The cleaner fix, if the input and output really differ, is to define two models (BookCreate and Book) and name them yourself.

Webhooks

OpenAPI 3.1 has a top-level webhooks section for requests your API sends to other people. FastAPI supports it:

python

class OrderEvent(BaseModel):
    order_id: int
    status: str


@app.webhooks.post("order-updated")
def order_updated(body: OrderEvent):
    """Sent when an order changes status."""

The function is never called. It exists so the document describes the payload your subscribers will receive.

Customize the whole document

When decorator arguments are not enough (adding a vendor extension, a logo, or a servers list that differs per environment), override app.openapi:

python

from fastapi.openapi.utils import get_openapi


def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title=app.title,
        version=app.version,
        summary=app.summary,
        description=app.description,
        routes=app.routes,
    )
    schema["servers"] = [{"url": "https://api.example.com"}]
    app.openapi_schema = schema
    return app.openapi_schema


app.openapi = custom_openapi

For a single operation, openapi_extra={...} on the decorator merges arbitrary keys into that operation. It is the right tool for vendor extensions such as x-codeSamples.

If you run behind a proxy with a path prefix, set root_path (or pass --root-path to the server) so the document's servers entry points at the public URL rather than the internal one.

Export the document for CI

Serving the document from a running app is fine for development. For CI you want a file you can lint, diff against the last release, commit, and hand to other tools. FastAPI can produce it without starting a server:

python

# scripts/export_openapi.py
import json
from main import app

with open("openapi.json", "w") as f:
    json.dump(app.openapi(), f, indent=2)

Run it in CI after tests, fail the build if the linter complains, and compare the result with the previous release to catch breaking changes before your users do. Our Spectral rules guide has a sensible starting ruleset.

Common mistakes

Raising HTTPException without declaring the response. The endpoint works; the document says it can only succeed.
Leaving operation IDs to the default. Fine for a demo, painful for an SDK.
Returning dict instead of a model. A function annotated -> dict produces an untyped response schema. Return a Pydantic model and the document gets a real schema.
Reading auth headers by hand. Use the fastapi.security dependencies so the scheme is documented.
Feeding 3.1 output to a 3.0-only tool. Upgrade the tool if you can. If you cannot, convert the file rather than downgrading your app's output.
Hiding internals with include_in_schema=False and forgetting about it. It hides the route from the document, not from the internet.

What to do with the document

Now you have an accurate OpenAPI 3.1 document coming out of your app and your CI. The value is in what reads it:

A documentation UI. FastAPI ships Swagger UI and ReDoc. You can serve any other UI that reads OpenAPI from a route with include_in_schema=False.
Client SDKs in Python, TypeScript and the other languages your users write.
An MCP server so AI agents can call the operations you choose.
Contract tests and breaking-change checks against the last published document.

Part two of this series covers each of those. For the short version today, the FastAPI API documentation page shows a two-line setup, and the FastAPI integration guide lists every option.

Frequently asked questions

Where is the FastAPI OpenAPI document?

At /openapi.json by default. Change it with FastAPI(openapi_url="/api/openapi.json"), or disable it with openapi_url=None.

Which OpenAPI version does FastAPI generate?

OpenAPI 3.1.0, since FastAPI 0.99.0. There is no built-in switch to emit 3.0.

How do I export the FastAPI OpenAPI document to a file?

Import the app and call app.openapi(), then write the result with json.dump. No server is needed.

Why are there Model-Input and Model-Output schemas in my document?

Since FastAPI 0.102.0, a model used for both requests and responses gets separate schemas, because fields with defaults are optional on input but always present on output. Pass separate_input_output_schemas=False to get one schema per model.

How do I change FastAPI operation IDs?

Pass generate_unique_id_function to FastAPI() or APIRouter() to change them everywhere, or operation_id="..." on a single route decorator.

How do I add authentication to the FastAPI OpenAPI document?

Use the dependencies in fastapi.security, such as APIKeyHeader, HTTPBearer or OAuth2PasswordBearer. They validate the request and register the matching security scheme in the document.

Learn: What is OpenAPI? · Generate an SDK from OpenAPI
Docs: FastAPI integration guide
Product: FastAPI API documentation — turn the document from this post into interactive docs with one package

OpenAPI with ASP.NET Core in .NET 9 and 10

Tue, 06 Oct 2026 00:00:00 GMT

ASP.NET Core generates OpenAPI documents on its own now. Since .NET 9, the Microsoft.AspNetCore.OpenApi package turns your minimal APIs and controllers into an OpenAPI document at runtime or at build time, and .NET 10 moved the default output to OpenAPI 3.1 and added XML comment support. You no longer need a third-party generator to describe your API.

This is part one of a three-part series. It is deliberately vendor-neutral: everything here uses Microsoft's packages and works the same whichever documentation UI, SDK generator, or linter you point at the result. Part two covers what you can build from the document (reference docs, SDKs, an MCP server), and part three walks through one concrete setup end to end.

Every API name below was checked against the Microsoft Learn pages for generating OpenAPI documents, customizing them, adding endpoint metadata and XML comment support as of September 2026.

Why Swashbuckle stopped being the default

For most of the ASP.NET Core era, the Web API template shipped with Swashbuckle, a community project that both generated the document and served Swagger UI. In .NET 9 the ASP.NET Core team removed it from the template and replaced it with first-party generation in Microsoft.AspNetCore.OpenApi.

That split matters more than it first looks. The new package produces the document and nothing else. It does not render a UI. That is a good separation: the document is the contract, and what you do with it (docs, client generation, contract tests, linting) is a separate choice. It also means a fresh .NET 9 or 10 project has an OpenAPI endpoint and no page to look at it with, which surprises people the first time.

If you are on an existing Swashbuckle project, nothing forces you to move. Swashbuckle still works. The reasons to switch are the ones below: 3.1 output, AoT compatibility, and a transformer API maintained by the same team that ships the framework.

.NET 9 vs .NET 10 at a glance

	.NET 9	.NET 10
Package	`Microsoft.AspNetCore.OpenApi`	`Microsoft.AspNetCore.OpenApi`
Default OpenAPI version	3.0	3.1
Version you can switch to	2.0	3.0
JSON Schema dialect	OpenAPI 3.0 schema subset	JSON Schema draft 2020-12
Nullable types	`nullable: true`	`type: ["null", "string"]` (3.1)
XML doc comments	Not read	Read by a source generator
YAML endpoint	No	Yes, via `.yaml` route suffix
Object model	`Microsoft.OpenApi` 1.x (`Microsoft.OpenApi.Models`)	`Microsoft.OpenApi` 2.x (`Microsoft.OpenApi`)

Microsoft's .NET 11 documentation already describes OpenAPI 3.2 as the default for that release. If you are reading this after .NET 11 ships, the pattern is the same; only the default changes.

Add OpenAPI generation

Install the package:

shell

dotnet add package Microsoft.AspNetCore.OpenApi

Then register the services and map the endpoint in Program.cs:

csharp

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOpenApi();

var app = builder.Build();

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

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

app.Run();

Run the app and open https://localhost:{port}/openapi/v1.json. v1 is the default document name. The IsDevelopment() guard is Microsoft's recommendation, not a technical requirement: it keeps the document off production by default so you opt in to publishing it.

Two small things the generator does that are easy to miss. It excludes HTTP methods OpenAPI does not recognise (Microsoft's example is QUERY) rather than emitting something invalid. And it formats numbers and dates with the invariant culture, so the document is identical whatever locale your build agent runs in. That second one matters when you diff documents in CI.

Choose the OpenAPI version

On .NET 10 you get 3.1 unless you ask otherwise. Some downstream tools still only read 3.0, and in that case you can pin it:

csharp

builder.Services.AddOpenApi(options =>
{
    options.OpenApiVersion = Microsoft.OpenApi.OpenApiSpecVersion.OpenApi3_0;
});

Our advice is to stay on 3.1 unless a specific consumer breaks. OpenAPI 3.1 aligns schemas with JSON Schema 2020-12, which is why nullable reference types come out as type: ["null", "string"] instead of the 3.0-only nullable: true keyword. Validators, generators and editors increasingly treat 3.1 as the baseline. If you want the full list of differences, we wrote them up in OpenAPI 3.1 vs 3.0.

On .NET 9 the default is 3.0 and there is no 3.1 option, so the only way to get 3.1 output is to upgrade.

Serve JSON, YAML, or both

The document is served as JSON by default. On .NET 10 you can serve YAML by giving the route a .yaml or .yml suffix:

csharp

app.MapOpenApi("/openapi/{documentName}.yaml");

Call MapOpenApi() twice if you want both. You can also move the route (app.MapOpenApi("/openapi/{documentName}/openapi.json")); keep the {documentName} parameter in it, because without it the framework falls back to a query parameter and Microsoft describes the result as unpredictable.

Describe your endpoints properly

A generated document is only as good as the metadata it can see. Without any, you get paths and types and very little else: no summaries, no operation IDs, and response codes only where the framework can infer them. Here is what to add, roughly in order of payoff.

Return typed results

For minimal APIs, TypedResults and the Results<...> union type carry response metadata at compile time, so the generator knows every status code an endpoint can return without you repeating it:

csharp

app.MapGet("/books/{id}", Results<Ok<Book>, NotFound> (int id, BookStore store) =>
    store.Find(id) is Book book
        ? TypedResults.Ok(book)
        : TypedResults.NotFound());

This is the single most useful habit. It keeps the document honest because the compiler, not a comment, decides what the endpoint returns.

Add summaries, descriptions, tags and operation IDs

Use the extension methods:

csharp

app.MapGet("/books/{id}", GetBook)
    .WithName("GetBook")
    .WithSummary("Get a book by ID")
    .WithDescription("Returns a single book, or 404 if the ID is unknown.")
    .WithTags("books")
    .ProducesProblem(StatusCodes.Status500InternalServerError);

Or the attribute equivalents on the handler: [EndpointName], [EndpointSummary], [EndpointDescription], [Tags], and [Description] on parameters. WithName sets the operationId. Set it deliberately. SDK generators use it to name methods, so GetBook becomes getBook() in TypeScript and get_book() in Python, and changing it later is a breaking change for anybody using a generated client.

For controllers, keep using [ProducesResponseType] for each status code, as you did with Swashbuckle.

To hide an endpoint from the document, use .ExcludeFromDescription() or the [ExcludeFromDescription] attribute.

Let the models describe themselves

Data annotations flow into the schema. [Required] marks a property as required, [Description] sets its description, and validation attributes such as [MaxLength] become schema constraints:

csharp

public record Book(
    [property: Required]
    [property: Description("The unique identifier for the book")]
    int Id,
    [property: Description("The book title")]
    [property: MaxLength(200)]
    string Title,
    string? Subtitle);

On .NET 10, Subtitle comes out as type: ["null", "string"]. The generator also infers required from constructor parameters when a type has exactly one public constructor, which is why records often need fewer attributes than you would expect. With more than one constructor, nothing is inferred.

Use XML comments (.NET 10)

.NET 10 reads the XML doc comments you probably already write. Enable the documentation file in the project:

xml

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

There is no extra code. A source generator intercepts your AddOpenApi() calls at compile time and adds the comments as summaries, descriptions, parameter docs and response descriptions. Supported tags include <summary>, <remarks>, <param>, <returns>, <response>, <example> and <deprecated>.

Two gotchas from the Microsoft docs that catch people:

A <response code="404"> tag only describes a response. It does not declare one. If the endpoint's metadata does not already include a 404 (from a typed result, Produces, or [ProducesResponseType]), the comment is silently dropped.
The source generator only recognises document names that are string literals. AddOpenApi("v1") works; AddOpenApi(documentName) with a variable gets no XML comments at all.

Customize the document with transformers

Sometimes metadata is not enough. You need to add a security scheme, set the info block, stamp every operation with a header, or fix how a type maps to a schema. That is what transformers are for. There are three kinds, and they run in a fixed order: schema transformers first, then operation transformers, then document transformers.

A document transformer that sets the title and description:

csharp

builder.Services.AddOpenApi(options =>
{
    options.AddDocumentTransformer((document, context, cancellationToken) =>
    {
        document.Info = new()
        {
            Title = "Bookstore API",
            Version = "v1",
            Description = "Books, authors and orders."
        };
        return Task.CompletedTask;
    });
});

An operation transformer that adds a 500 response everywhere:

csharp

options.AddOperationTransformer((operation, context, cancellationToken) =>
{
    operation.Responses ??= new OpenApiResponses();
    operation.Responses.Add("500", new OpenApiResponse { Description = "Internal server error" });
    return Task.CompletedTask;
});

A schema transformer that gives decimal a decimal format instead of double:

csharp

options.AddSchemaTransformer((schema, context, cancellationToken) =>
{
    if (context.JsonTypeInfo.Type == typeof(decimal))
    {
        schema.Format = "decimal";
    }
    return Task.CompletedTask;
});

For anything that needs services from dependency injection, implement IOpenApiDocumentTransformer (or the operation and schema equivalents) and register it with AddDocumentTransformer<T>(). Microsoft's own example uses this to read the registered authentication schemes and add a matching bearer security scheme to components.securitySchemes, which is the pattern to copy if your API uses JWT bearer auth. Security schemes matter downstream: documentation UIs use them to render an authentication form, and SDK generators use them to decide what the client constructor asks for.

.NET 10 also lets transformers generate a schema for any C# type with context.GetOrCreateSchemaAsync(...) and register it with document.AddComponent(...), which is handy for adding a shared ProblemDetails error schema to every operation.

Upgrading transformers from .NET 9 to .NET 10

This is the one real migration cost. .NET 10 moves to version 2 of the Microsoft.OpenApi object model. In practice:

using Microsoft.OpenApi.Models; becomes using Microsoft.OpenApi;.
Collections such as components.securitySchemes are typed by interface, for example Dictionary<string, IOpenApiSecurityScheme>.
References use dedicated types such as new OpenApiSecuritySchemeReference("Bearer", document) instead of an OpenApiReference object on the scheme.
Collections may be null, so initialise them (operation.Responses ??= new OpenApiResponses();) before adding to them.

Compare the .NET 9 and .NET 10 versions of the customization page side by side when you port a transformer; the samples are the same code in both object models.

Generate several documents

One app can publish more than one document, for example a public and an internal API, or v1 and v2:

csharp

builder.Services.AddOpenApi("public");
builder.Services.AddOpenApi("internal", options =>
{
    options.AddDocumentTransformer<BearerSecuritySchemeTransformer>();
});

app.MapGet("/books", ListBooks).WithGroupName("public");
app.MapGet("/admin/audit", GetAuditLog).WithGroupName("internal");

Each document is served at /openapi/{name}.json. By default an endpoint lands in the document whose name matches its group name, and endpoints with no group name appear in every document. Override ShouldInclude on the options if you need other rules. Each document gets its own transformers, so the internal one can carry auth requirements the public one does not.

Generate the document at build time

Serving the document from a running app is fine for development. For CI you usually want a file: something you can lint, diff against the last release, commit, and hand to other tools without booting the app. Add the build-time package:

shell

dotnet add package Microsoft.Extensions.ApiDescription.Server

Now dotnet build writes the document to the output directory. Two properties in the project file make it more useful:

xml

<PropertyGroup>
  <OpenApiDocumentsDirectory>.</OpenApiDocumentsDirectory>
  <OpenApiGenerateDocumentsOptions>--file-name openapi</OpenApiGenerateDocumentsOptions>
</PropertyGroup>

OpenApiDocumentsDirectory is relative to the project file, so . writes next to your .csproj. OpenApiGenerateDocumentsOptions also accepts --document-name v2 to emit only one document, and --openapi-version OpenApi3_1 to pick the version at build time. YAML output at build time is not supported yet.

A caution: build-time generation runs your app's startup code to discover endpoints. If Program.cs connects to a database or reads secrets on startup, the build can fail on a clean agent. Microsoft's suggestion is to wrap that code in a check that Assembly.GetEntryAssembly()?.GetName().Name is not "GetDocument.Insider", which is the entry assembly name during build-time generation.

Common mistakes

Leaving operation IDs to chance. Without WithName, generated names are unstable, and every SDK built from the document inherits the instability.
Documenting responses the endpoint never declares. XML <response> tags and descriptions do nothing without response metadata. Use typed results.
Using a variable for the document name on .NET 10 and wondering where the XML comments went.
Pinning OpenAPI 3.0 "to be safe" and losing accurate nullability. Pin only for a consumer that needs it.
Serving the document publicly by accident. If you remove the IsDevelopment() guard, remember MapOpenApi() returns a normal endpoint, so .RequireAuthorization() and .CacheOutput() work on it.
Never validating the output. Run the generated file through a linter in CI. Our Spectral rules guide covers a sensible starting ruleset.

What to do with the document

At this point you have a correct, versioned OpenAPI document coming out of your build. On its own it is a JSON file. The value comes from what reads it:

A documentation UI. Microsoft's using OpenAPI documents page shows Swagger UI, ReDoc and Scalar, and recommends enabling any of them only in development unless you mean to publish.
Client SDKs generated from the document, in C# and the languages your users actually write.
An MCP server so AI agents can call the operations you choose.
Contract tests and breaking-change checks that compare this build's document with the last release.

Part two of this series covers those in turn. If you want the short version for .NET today, the .NET API documentation page shows the two-line setup, and the ASP.NET Core integration guide lists every option.

Frequently asked questions

Do I still need Swashbuckle in .NET 9 or .NET 10?

No. Microsoft.AspNetCore.OpenApi generates the document. You only need a separate package for a UI, and you can choose any UI that reads OpenAPI. Existing Swashbuckle projects keep working if you are not ready to move.

Which OpenAPI version does ASP.NET Core generate?

OpenAPI 3.0 on .NET 9 and OpenAPI 3.1 on .NET 10. Set options.OpenApiVersion in AddOpenApi to change it on .NET 10.

Where is the OpenAPI document served?

At /openapi/{documentName}.json, which is /openapi/v1.json for the default document. Pass a different route to MapOpenApi() to move it, and use a .yaml suffix on .NET 10 for YAML.

Why are my XML comments missing from the OpenAPI document?

Check three things: GenerateDocumentationFile is true, you are on .NET 10, and the document name passed to AddOpenApi is a string literal. Response descriptions also need the status code to be declared by the endpoint.

How do I add JWT bearer authentication to the document?

Use a document transformer that adds an HTTP bearer scheme to components.securitySchemes, and an operation transformer if you need to skip endpoints marked [AllowAnonymous]. Microsoft's customization page has a complete example.

Can I generate the OpenAPI document without running the app?

Yes. Add Microsoft.Extensions.ApiDescription.Server and the document is written during dotnet build. It still executes your startup code, so guard anything that needs external resources.

Learn: What is OpenAPI? · OpenAPI 3.1 vs 3.0
Docs: ASP.NET Core integration guide
Product: .NET API documentation — turn the document from this post into interactive docs with one NuGet package

Migrating off Stainless: week-one checklist

Thu, 01 Oct 2026 00:00:00 GMT

If your SDKs were generated by Stainless, the most useful thing you can do this week is not choosing a new generator. It is making sure that whatever you choose, you can prove your users' code still works afterwards. This post is a five-day checklist for that first week: what to inventory, what to snapshot, which credentials to find, and which test to write before anyone regenerates anything.

Some context, briefly. On 18 May 2026 Stainless announced it is joining Anthropic and winding down its hosted products, including the SDK generator, with new signups, projects and SDKs closed the same day. The SDKs you already generated are yours. What stops is regeneration.

We have written about this three times already, and this post deliberately does not repeat them:

The Stainless SDK generator wind-down is the full account: what changed, how to evaluate the options, and a key-by-key stainless.yml mapping.
Stainless alternatives compares the generators you can move to, including where each one beats us.
How to migrate from Stainless to Scalar is the step-by-step guide if you have already picked Scalar.

This one sits before all of them. Nothing on this list depends on which generator you pick, and most of it gets harder the longer you wait.

The week at a glance

Day	Goal	Output you should have by the end of the day
1	Inventory	One table listing every SDK, package, repository and owner
2	Snapshot	A committed record of each SDK's public surface, tagged
3	Credentials and access	A list of every token, app and workflow that publishes your SDKs
4	Compatibility harness	A test suite that exercises every public method of the current SDK
5	Guardrails and communication	A CI check on API changes, a decision date, and a note for your team

You can compress this into two days on a small API or stretch it over two weeks on a large one. The order matters more than the pace.

Day 1: Inventory what you actually ship

Most teams know roughly which SDKs they have. Fewer can list, without looking, every package name in every registry, which repository each one is built from, and who last touched it. Start there, because every later step refers back to this table.

Open your stainless.yml. Its targets block lists every language you generate. For each target, record:

Field	Where to find it
Language and package name	`targets` in `stainless.yml`, then the registry page (npm, PyPI, Maven Central, RubyGems, Go module path)
Production repository	The repository your releases are published from
Current published version	The registry page
Date of the last regeneration	The most recent generated commit in the production repository
Files with hand-written changes	Commits in the repository that were not made by the generator
Owner	A named person, not a team alias
Known heavy users	Your largest customers or internal services that depend on the SDK

Two rows people forget. First, targets: terraform and targets: sql: if you generated either, flag them now, because they narrow your options more than anything else. Second, docs: if you used the Stainless Docs Platform, add a row for that repository too, and note that it lives in the stainless-sdks GitHub organisation rather than yours.

The "files with hand-written changes" column deserves real time. Stainless merged custom code into generated files, so your edits are interleaved with generated code rather than sitting in a separate folder. Run git log on each production repository, filter out the generator's commits, and list every file a human changed. You will need this list on day 4 and again on the day you regenerate.

Day 2: Snapshot the public surface

Your public surface is every class, method, parameter and type your users can import. It is the thing a migration must not break, and today is the last day it is guaranteed to match what is installed in the wild. Record it now, in a form a machine can compare later.

Start with what you already have. Stainless SDK repositories include an api.md that lists every method grouped by resource. Copy it somewhere safe and tag the commit. That is your human-readable baseline.

Then add a machine-readable one per language. These are the tools we would reach for; any equivalent works.

TypeScript

# API Extractor writes a report of every exported declaration.
# Run init once, point it at your built .d.ts entry point, then run.
npx @microsoft/api-extractor init
npx @microsoft/api-extractor run --local
git add etc/*.api.md
git tag sdk-surface-baseline

Python

# Griffe dumps the public API and can check a later version against it.
pip install griffe
griffe dump your_package > api-baseline.json
git tag sdk-surface-baseline
# Later: griffe check your_package --against sdk-surface-baseline

# apidiff compares the exported API of two versions of a package.
go install golang.org/x/exp/cmd/apidiff@latest
apidiff -w baseline.export github.com/your-org/your-sdk-go
git tag sdk-surface-baseline

For Java, Kotlin, Ruby and the rest, the principle is the same: produce a file that lists every public symbol, commit it, and tag the commit. If there is no tool you trust, a script that imports the package and walks its exports is fine.

Also capture the things a signature report misses:

The client class name and constructor options.
The environment variables the client reads for credentials and base URL.
Default timeouts, retry counts and which status codes trigger a retry.
How pagination is exposed: auto-iterating lists, page objects, cursors.
Error class names and their hierarchy.

These are behaviours users depend on without ever writing them down. Write them down now.

Day 3: Find every credential, app and workflow

Today is about control. When you move, you need to be able to publish new versions of the same packages from a pipeline you own. Find out now whether you can.

Work through the inventory table and, for every package, answer:

Who owns the package in the registry? On npm, npm owner ls <package> lists maintainers. On PyPI, check the project's collaborators and any trusted publishers. On Maven Central and RubyGems, check the namespace and gem owners. If the only owner is a person who has left, fix that this week.
What publishes it today? Read every workflow in .github/workflows in the production repository. Note each secret it references and where the secret is stored.
Which GitHub Apps can write to the repository? Check the organisation's installed apps and note what the Stainless app can access. Our migration guide covers removing it; for now, the goal is to know its scope and to make sure nothing breaks when it goes.
Is anything pointing back at Stainless infrastructure? Search the repositories for stainless in workflow files, scripts and READMEs.

The output is a short list: package, owner, publishing workflow, secret names, and any access that depends on Stainless. If a row has a gap, that is your first real task, and it is much easier to close while nothing is on fire.

Day 4: Build a compatibility harness

The snapshot from day 2 tells you if a signature changed. It does not tell you whether a user's code still runs. For that, you want a small test suite that uses the current SDK the way your users do, and that you can later point at any regenerated SDK unchanged.

Keep it simple:

One call per public method. Walk api.md and write a test that calls each method with realistic arguments. Assert on the shape of the result, not on exact values.
Run it against a mock server. Your OpenAPI document already describes every response, so a mock server can answer these calls without touching production. The Scalar mock server is one option; any OpenAPI mock server works.
Cover the behaviours from day 2. A test that pages through a list, a test that triggers a retry on a 429, a test that catches the typed error on a 404, and a test that constructs the client from environment variables alone.
Compile your README snippets. Copy every code sample from your README and docs into the test suite. They are the code your users copied first, so they are the most likely to break.

Run the suite against the current published version and commit it green. When you evaluate a generator, you install its output in place of the current SDK and run the same suite. A failure is a breaking change you found before your users did.

This is also where the day-1 list of hand-edited files pays off. Every hand-written helper should have at least one test in the harness, because it is the code most likely to be lost in regeneration.

Day 5: Put guardrails on the API and tell your team

Nothing breaks until your API changes. So the last step is to make sure the next API change cannot ship quietly while the SDKs are frozen.

Add a CI check on the OpenAPI document. Diff the document on every pull request against the one your SDKs were last generated from. Any change to a path, parameter, or schema should fail the check, or at least require an explicit approval that says "the SDK will not reflect this yet". This turns an invisible gap into a visible decision.

Set a decision date. The real deadline is not Stainless's; it is your next API change that users need in the SDK. Put a date on the calendar that is comfortably before it.

Write down how you will evaluate options. The wind-down page has the long version. The short version is one question for every vendor: how does my existing public surface survive? You now have the tools to check the answer yourself: the snapshot from day 2 and the harness from day 4.

Tell your team. A short internal note is enough:

Our SDKs were generated by Stainless, which has stopped accepting new work. Published SDKs keep working. Until we move, SDK changes are frozen and API changes that affect the SDK need sign-off from [owner]. We have a surface snapshot and a compatibility test suite, and we will decide on a replacement by [date].

You do not need to tell customers anything yet, unless your API is about to change in a way the SDK must reflect. When you do migrate, the goal is that there is nothing to tell them: same package names, same imports, same method names, a normal minor version bump.

What not to do in week one

Do not regenerate from the OpenAPI document alone into your main branch. Any generator will produce a working SDK with a different public surface. Try it on a branch if you like, then run the day-4 harness and read the failures. It is an instructive afternoon.
Do not rename packages. A new package name forces every user to change their install and their imports.
Do not delete stainless.yml. It holds your resource tree, method names and pagination rules, and some generators, including ours, read it directly.
Do not remove the Stainless GitHub App before you can publish another way. Remove it once the new pipeline has shipped a release.
Do not let the freeze become permanent. Every week of API changes you defer is another week of drift to reconcile later.

Where to go next

If you have finished the checklist, you are in a better position than most teams to evaluate options, because you can test the claims. Start with the wind-down write-up for the evaluation criteria, then Stainless alternatives for the field. If you choose Scalar, the migration guide picks up exactly where this list ends: import your OpenAPI document and stainless.yml, then diff the generated api.md against the snapshot you took on day 2.

Frequently asked questions

Do my Stainless-generated SDKs stop working?

No. Published packages keep working and the code is yours. What stops is regenerating them when your API changes.

What should I do first when migrating off Stainless?

Inventory every SDK you ship and snapshot its public surface. Both are independent of which generator you choose, and both are easier to do before anything changes.

How do I check that a new generator did not break my SDK?

Compare the new SDK's public surface with your snapshot, then run a compatibility test suite written against the current SDK. Signature diffs catch renamed methods; the tests catch changed behaviour such as pagination and retries.

Can I keep the same package names after migrating?

Yes. The packages and registries are yours. Keeping the names is the most important thing you can do for your users, and any serious migration should support it.

Is there a deadline for leaving Stainless?

Stainless's announcement does not give an end date for existing projects, and we had not seen one published when this post was written. Your practical deadline is your next API change that your SDK users need.

Learn: Generate an SDK from OpenAPI · Build vs buy an SDK
Docs: How to migrate from Stainless to Scalar
Product: SDK generator — reads your stainless.yml so your users' call sites keep working

Stainless facts in this post come from Stainless's own announcement and documentation, as of 26 September 2026. If Stainless publishes a timeline or anything here is out of date, please open an issue and we will correct it.

Release notes: 19–26 September 2026

Tue, 29 Sep 2026 00:00:00 GMT

A big week for OpenAPI 3.2. The API reference and API client now understand querystring parameters, custom HTTP methods through additionalOperations, the new dataValue and serializedValue examples, streaming item schemas, and OAuth device authorization. There is also a new Copy as Markdown button, API client translations, live streaming response views, and a batch of fixes and hardening. A few changes need attention when you upgrade; they are collected at the end.

Everything below comes from the changelogs of @scalar/api-reference and @scalar/api-client and the commit history of the monorepo for the week. Each item links to its pull request.

Versions released this week

Package	Versions	Release dates
`@scalar/api-reference`	1.70.0, 1.71.0, 1.72.0, 1.72.1	21, 22, 24 and 25 September
`@scalar/api-client`	3.19.3, 3.20.0, 3.21.0, 3.21.1	21, 22, 24 and 25 September

The integrations (ASP.NET Core, FastAPI, NestJS, Hono and the rest) pick up API reference changes through their normal releases.

OpenAPI 3.2 support

OpenAPI 3.2 adds several features that did not have a home in 3.1. This week, a lot of them landed in both the reference and the client.

in: querystring parameters. A parameter can now describe the entire query string as one piece of content, for example a JSON object. The reference renders its schema, the client lets you edit the whole query string, and generated request URLs and code samples encode it correctly. Named query parameters keep their existing encoding when they sit alongside whole-query content. (#10189)
additionalOperations and custom HTTP methods. Operations using methods outside the standard set, such as QUERY or PROPFIND, now appear in navigation, documentation, callbacks and the client, with their original spelling preserved when displayed, sent and turned into code samples. The client shows a clear error for methods browsers refuse to send (CONNECT, TRACE, TRACK), and request bodies are preserved for extension methods. (#10186)
dataValue and serializedValue examples. Named parameters use these new example fields in the editor, in outgoing requests and in code samples, without encoding an already serialized value twice. Optional parameters with one of these examples are now enabled by default, matching the older value examples. (#10322) Example selection is shared across request bodies, response examples and snippets. (#10208)
Streaming item schemas. Request body examples and schema views support 3.2 streaming item schemas, and generated examples are framed as JSON Lines, JSON Sequence or server-sent events. cURL snippets use --data-binary for streaming media types. (#10178)
OAuth device authorization. The client supports the device authorization flow, with verification codes, cancellable token polling, stored credentials and OAuth metadata discovery. (#10191)
XML examples. Examples are now generated from schema XML metadata, including attributes, namespaces, array wrappers and 3.2 text and CDATA nodes, and the same serialization is used for request bodies, code samples, response examples, mock responses and Markdown. (#10192)

Behind these, the workspace store and editor moved to OpenAPI 3.2 schemas while continuing to accept 3.1 documents. The editor offers 3.2 fields to documents that declare 3.1 as well; it does not certify that your document conforms to the version it declares. (#10177)

New in the API reference

Copy as Markdown. Operations and webhooks have a Copy as Markdown button in both layouts, handy for pasting an endpoint into an issue, a pull request or a chat with an AI assistant. (#10222) It also respects document-defined additional operations. (#10186)
expandAllParameters option. Defaults to true. Set it to false to start operation parameters collapsed and expand each one on click. (#10283)
Searchable document selector. The multi-document selector gained title filtering and keyboard-friendly search. (#10269)
Discriminator values in schema selectors. oneOf and anyOf selectors show discriminator mapping values next to schema names. (#10317)
Response variant picker. Generated response examples with anyOf or oneOf variants get a picker. (#10203)
Response example descriptions. Example summaries and descriptions are shown with their payloads. (#10249)
AsyncAPI payload examples are generated from JSON Schema when no explicit example is provided. (#10217)
SDK samples follow the example switcher. SDK code samples can be linked to named request body examples. (#10310)
Clearer authentication tooltips, with separate headings, readable scheme types, and API key locations and names. (#10335)

New in the API client

Live streaming responses. JSON Lines, JSON Sequences and multipart responses are displayed as they arrive instead of after the full response completes, with cancellation, malformed-record reporting and bounded display limits. (#10207)
Translations. The client UI, including the client embedded in the API reference, can be translated through localization.translations.apiClient, and ships with English, Russian, Spanish, French, German, Simplified Chinese, Arabic and Portuguese. (#10175)

Performance

The API client modal now loads the first time you open Test Request, not when the reference mounts, and shows loading feedback while it downloads. (#10284)
The agent drawer and chat load when first opened. (#10287)
External examples load on demand when they are visible or when Test Request opens, instead of all at once while the document loads. (#10240)

Fixes

API reference

Nested object boundaries are preserved for properties composed from multiple allOf schemas. (#10336)
enum values are intersected when merging allOf schemas, so inherited properties show only allowed values. (#10232)
Deep-linked headings stay visible below sticky or fixed headers. (#10253)
Sidebar navigation no longer scrolls past operations and models in themes with decorative backgrounds. (#10333)
Server-rendered accordion headers, auth tables and the initial sidebar selection now hydrate correctly. (#10313)
Colored x-badges pick black or white text from the background's lightness. (#10300)

API client

Long response bodies stay scrollable in narrow layouts. (#10350)
Optional form fields are included when you select files or edit values. (#10334)
Optional header, query and cookie rows with a pre-populated default or enum value are enabled automatically instead of being silently dropped. (#10255)
Typing a header, cookie or query parameter no longer creates duplicate rows or loses focus. (#10281)
Parameter edits are preserved when another parameter changes. (#10303)

Security hardening

Several fixes this week harden how documents and configuration are handled. We recommend upgrading.

Configuration data embedded in inline scripts is escaped in client-side rendering. (#10344)
The workspace store prevents prototype pollution in nested object operations. (#10342)
ts-deepmerge was updated in the object utilities to prevent method overrides. (#10338)
The mock server restricts AsyncAPI external references. (#10343)
Validation bounds union scoring depth, and trailing-dot encoding runs in linear time. (#10315, #10341)

Elsewhere in the monorepo

The OpenAPI upgrader gained a best-effort upgrade mode, preserves Swagger 2.0 x-nullable, preserves semantics when upgrading to OpenAPI 3.2, and migrates tag groups to the 3.2 tag hierarchy. (#10346, #10306, #10211, #10276)
The mock server supports streaming item schemas and document origins and exports. (#10176, #10286)
JavaScript snippets preserve nested arrays. (#10305)
OpenAPI-to-Markdown renders each shared schema once per page and preserves examples and schema details. (#10329, #10275)
This blog now has an RSS feed. (#9984)

Upgrade notes

Most of this week is additive. Check these if they apply to you:

Sticky headers on embedding sites (1.72.1). Scalar no longer discovers host page headers automatically when scrolling to content. If you embed the reference under your own fixed or sticky header, register it with the data-scalar-scroll-header attribute, or reserve its height with --scalar-custom-header-height. (#10333)
XML snapshots (1.72.1, 3.21.1). Mock server XML responses now use the shared schema-aware serializer. If you snapshot XML responses in tests, expect them to change. (#10192)
Custom HTTP method types (1.72.0, 3.21.0). Traversed operation methods use the exported OperationMethod type, which accepts custom strings. If you consume these types, handle unknown methods; exhaustive checks over a fixed method set no longer apply. (#10186)
Optional parameters with examples (1.72.0, 3.21.0). Optional parameters with dataValue or serializedValue examples are enabled by default, so they are sent unless the user unchecks them. (#10322)
Workspace store import paths (1.71.0, 3.20.0). The OpenAPI 3.1 loose-schema generator was removed from @scalar/workspace-store. Import from @scalar/workspace-store/schemas/v3.2/openapi/index and .../v3.2/openapi/reference instead. (#10177)
Edited request bodies (1.71.0, 3.20.0). Editing a request body replaces an authored externalValue URL with the edited inline value in the workspace and exported API description. (#10208)

Found a problem after upgrading? Open an issue with the version and a minimal OpenAPI document, and we will take a look.

Learn: What is an API reference? · What is an API client?
Docs: API reference configuration
Product: API client — try this week's OpenAPI 3.2 support against your own document

We wrote up the Stainless wind-down

Sun, 16 Aug 2026 00:00:00 GMT

Stainless announced on 18 May 2026 that it is joining Anthropic and winding down all of its hosted products, including the SDK generator. New signups, projects, and SDKs closed the same day.

Three months on, the thing we keep hearing from teams in that position is not "which generator is best". It is a narrower and more awkward question: my users have already written code against my SDK — how do I move without breaking them?

That question has a specific answer, and it is not the one most migration content gives. Your OpenAPI document was never the hard part of leaving Stainless. It is yours and every generator reads it. The hard part is stainless.yml — the file that decides which operations become which namespaces, what each method is called, which pagination scheme each list endpoint uses, and what your package is named in every language. None of that is expressible in OpenAPI. Regenerate from the specification alone with any tool and you get a working SDK with a different public surface, which is a breaking change your users absorb.

So we wrote a full account of the situation: The Stainless SDK generator wind-down.

It covers what Stainless actually said and what it did not say, what keeps working and what stops, and an assessment of the realistic options — OpenAPI Generator, Speakeasy, Fern, APIMatic, liblab, stainful, oagen, and Scalar — with the places each of them beats us stated plainly. Speakeasy generates Terraform providers and we do not. Fern's generators are Apache-2.0 and ours are not. OpenAPI Generator is free and cannot be wound down by anybody. If one of those is your requirement, the page says so.

It also gets specific about the part we do well. Scalar reads stainless.yml as an input, so your resource tree, method names, pagination schemes, and per-language package names carry across and your users' call sites keep working. The page includes a key-by-key mapping between the two config formats, including the places where it does not carry — targets: terraform and targets: sql have no Scalar equivalent, and openapi.transforms has to be applied upstream.

There is a section at the end for people who are not choosing Scalar, because most of the migration work is the same whoever you pick, and some of it is worth doing this week regardless. Snapshot your current public API surface while you can still regenerate it. Find your hand-written code before you regenerate anything. Get your docs repository out of the stainless-sdks organisation.

If you are migrating and something on that page is wrong, unfair, or out of date — including if you work for one of the companies named on it — open an issue and we will correct it.

Read the full piece →

Scalar's 2025 Open Source Pledge

Sat, 11 Apr 2026 00:00:00 GMT

What is Open Source Pledge?

You can read more about it here, but in short, it's paying Open Source maintainers. The minimum to participate is $2,000 per full-time employed developer per year.

Open source is the foundation everything we build sits on. In 2025, Scalar is made up of 10 developers and contributed $21,232 directly to open source maintainers -- $2,123 per developer.

We sponsored the following maintainers and projects:

tiangolo (FastAPI)
SaltyAom (ElysiaJS)
hey-api
litestar-org (LiteStar)
colinhacks (Zod)
daveshanley (libopenapi)
mholt
yusukebe (Hono)
Aslemammad
pi0 (Nuxt / UnJS)
typst
MathurAditya724
fuma-nama
thibaultleouay (OpenStatus)
dmonad (Yjs)
marijnh (CodeMirror / ProseMirror)
LinusBorg (Vue.js)

Most of us got into engineering through open source. We're glad to give back -- and we're proud to be members of the Open Source Pledge again in 2025.

-- Marc, CEO & co-founder, Scalar

Too Long; Didn't Read; Used MCP

Wed, 25 Mar 2026 00:00:00 GMT

It's 2026, who even READS the documentation for your API. Just boot up an MCP based on your OpenAPI document (using Scalar), and share it with your users or your team (agents).

And then enhance any trillion dollar frontier model with your MCP server, that has all the context of how your API is defined. We'll show exactly how in the UI.

If you want to add our Scalar Galaxy example, hack this into your terminal:

bash

npx add-mcp https://mcp.scalar.com/mcp/67f954ca-123c-423b-b601-7284cfac3aff

That's it? That's it. Open your thing and ask it something related to the API.

claude, give me the curl for creating a new planet, buddy
make no mistakes

Let it do its work…

⏺ Let me search the available APIs for a planet creation endpoint.

⏺ scalar-galaxy-mcp - search-openapi-operations (MCP)(question: "create a new planet")

… and you'll be amazed how accurate (and token-efficient and fast) it will reply:

Here's your curl:

curl -X POST https://galaxy.scalar.com/planets \
  -H "Content-Type: application/json" \
  -d '{ … }'

Expects: 201 Created with the planet object (including a server-assigned id).

The only required field is name — everything else is optional.

(You can stop reading here, the following part is for all the great companies and enterprises using Scalar. Just open the dashboard and spin up your MCP in less than 60 seconds: https://dashboard.scalar.com, that's fine.)

Sometimes, you don't want to share the docs publicly, no matter if it's in the browser or it's the MCP server. Your internal APIs, the new APIs you're about to release, the staging APIs… They are not for anyone. No worries, we got you.

Set your MCP to "private" and share the URL with your team. They'll be able to authenticate using OAuth. This means their LLM will open a browser, where they can authenticate with Scalar to access your secret API (if they are on your team). Here's a video how easy it is:

This is how documentation works for everyone (agents).

Use your API in Cursor

Tue, 17 Mar 2026 00:00:00 GMT

We've been hard at work figuring out how to get Agent Scalar as close as possible to your favorite tools with as little overhead as possible, and here is what we came up with:

Agent MCP Servers allow you to take your existing OpenAPI document and expose it via an MCP server with all the performance benefits of Agent:

Managing API Authentication

API authentication with AI tools is just a big headache. With Agent MCP servers you can preconfigure the authentication specified in your OpenAPI document so the LLM can operate the MCP tools without having to worry about how to fetch a token or navigate the auth structure.

MCP Server Privacy

By default, the access to the MCP servers you set up is restricted and requires a Scalar API Key in order to access and use the tools.

Try it in the Scalar Dashboard. :-)

Mar 17, 2026

Introducing Agent

Thu, 05 Mar 2026 00:00:00 GMT

Making your AI Agents talk to APIs is easy and fun. It's just that bigger APIs are a worst-case workload for agents. Raw API definitions in the prompt overflows context so easily. I mean, we tried that. But all we got is hallucinated endpoints and unreliable responses.

That's something MCP helps with. You just wrap your API as MCP tools, and you're good to go. That's what we thought. Actually, the repeated schemas come with a cost (tokens), too.

I'm glad to say, we found something better. It's called Agent and our newest product, tightly integrated with our set of tools for your API. And here is why it might be better than your average MCP server:

Agent keeps the tool surface fixed and super small. It fetches just-in-time details. The result is smaller context, fewer steps, and better routing. And happy agents. :-)

Get Started

Chat with Agent Create your own MCP

The problem

If you dump the full OpenAPI document into the prompt, you often blow past the model's context window before the model can do any work. That's exactly what happens with, for example, the Zoom Meetings API.

Even when the API is smaller, like Notions API, raw OpenAPI is so expensive: It works, sure, but you pay a steep token tax every run. MCP reduces cost a lot, but native MCP still carries schema tokens for every single endpoint.

Agent collapses that into three tools and pulls only the schema it needs.

Benchmarking what we built

We ran a few benchmarks to test Agent with real-world APIs. And the results are so good, but take a look yourself:

Benchmark setup

We ran identical tasks across three approaches:

Raw OpenAPI documents in prompt
Native MCP server (one tool per endpoint)
Agent (3 tools: summarize, search and execute)

We used Zoom Meetings API (list, create, update) and Notions API (search, create page, get workspace). Example Notion prompts are aligned with Notion's MCP tools guide.

Token counting was done with tiktoken.

Zoom Meetings

Summary

Mode	Task	Runs	Success	Avg Tokens	Avg Latency	Avg Steps
raw-openapi	List upcoming meetings	1	0%	385797	2205 ms	0.0
native-mcp	List upcoming meetings	1	100%	20179	47887 ms	6.0
agent-scalar	List upcoming meetings	1	100%	5531	23029 ms	2.0
raw-openapi	Create a meeting	1	0%	385791	2011 ms	0.0
native-mcp	Create a meeting	1	100%	95474	46529 ms	6.0
agent-scalar	Create a meeting	1	100%	39327	20637 ms	2.0
raw-openapi	Update a meeting	1	0%	385792	1978 ms	0.0
native-mcp	Update a meeting	1	100%	95406	45189 ms	6.0
agent-scalar	Update a meeting	1	100%	12674	13367 ms	2.0

Schema Cost (200k context)

Approach	Tools	Token cost	Schema Tokens	All-in Tokens	Context used (200k)
Raw OpenAPI Spec in prompt	--	295656	0	295656	147.8%
Native MCP (full schemas)	183	89281	89530	178811	89.4%
Native MCP (required params only)	183	5504	89530	95034	47.5%
Agent (MCP tools)	3	412	412	412	0.2%

Notion

Summary

Mode	Task	Runs	Success	Avg Tokens	Avg Latency	Avg Steps
raw-openapi	Search for budget approval docs	1	100%	95819	114858 ms	1.0
native-mcp	Search for budget approval docs	1	100%	14725	39663 ms	6.0
agent-scalar	Search for budget approval docs	1	100%	1873	51474 ms	3.0
raw-openapi	Create project kickoff page	1	100%	96479	75803 ms	1.0
native-mcp	Create project kickoff page	1	100%	14643	51163 ms	6.0
agent-scalar	Create project kickoff page	1	100%	1454	103488 ms	2.0
raw-openapi	Which workspace am I connected to?	1	100%	95490	22175 ms	1.0
native-mcp	Which workspace am I connected to?	1	100%	14385	27013 ms	6.0
agent-scalar	Which workspace am I connected to?	1	100%	1206	27580 ms	3.0

Schema Cost (200k context)

Approach	Tools	Token cost	Schema Tokens	All-in Tokens	Context used (200k)
Raw OpenAPI Spec in prompt	--	69114	0	69114	34.6%
Native MCP (full schemas)	26	2104	12803	14907	7.5%
Native MCP (required params only)	26	829	12803	13632	6.8%
Agent (MCP tools)	3	400	400	400	0.2%

The Results

Guess who's the clear winner with just 0.2% of your context window: Agent. Why is that?

Native MCP scales with endpoint count. Agent does not. Three tools cover the entire API.
Instead of loading the full API definition upfront, the agent calls a tiny version, with just the endpoints and schemas it needs.
The schema footprint is tiny (hundreds of tokens) even for large APIs like the Zoom Meetings API.

How it works

Upload your OpenAPI document to Scalar.
Scalar augments it for search and execution.
Agents connect via MCP with three tools:
- summarize-openapi-specs (short summary of specs and available endpoints)
- search-openapi-operations (minified OpenAPI documents for the endpoints matching the user's search), and
- execute-request

Try it

You can use Agent in two ways:

Chat UI: upload your OpenAPI and chat at agent.scalar.com.
Agent SDK: connect to Scalar MCP servers from your agent runtime (Vercel AI SDK, OpenAI Agents SDK, Anthropic Claude SDK).

import { Agent, MCPServerStreamableHttp, run } from '@openai/agents'
import { agentScalar } from '@scalar-org/agent-sdk'

const scalar = agentScalar({
  agentKey: 'YOUR_AGENT_KEY',
})

const session = await scalar.session()

const serverOptions = session.createOpenAIMCPServerOptions()
const servers = serverOptions.map((opts) => new MCPServerStreamableHttp(opts))
await Promise.all(servers.map((s) => s.connect()))

const agent = new Agent({
  name: 'api-agent',
  instructions: 'You help users interact with APIs.',
  mcpServers: servers,
})

const result = await run(agent, 'pls list available endpoints in the zoom api thanks')

await Promise.all(servers.map((s) => s.close()))

Agent is able to scale across N APIs that you want your agent to have access to, without flooding the context window and yielding the most accurate tool calling. Crazy, eh?

Mar 5, 2026

How to set up an OpenAPI mock server

Tue, 19 Aug 2025 00:00:00 GMT

To create a mock server for your OpenAPI document, download the Scalar CLI:

npm -g install @scalar/cli

Note: There’s another scalar CLI which is bundled with Git. If you run into naming conflicts and never use the other CLI anyway, you can replace it like this:
npm -g --force install @scalar/cli

Once installed, run the document mock command pointing at your OpenAPI document (no matter if it’s JSON or YAML, local or remote).

scalar document mock https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/3.1.json

This launches a fully functional HTTP server that responds to every endpoint in your OpenAPI file with realistic mock data based on your schema definitions. You’ll see a color-coded output of available paths for you to make requests to:

When you make those requests, you’ll get responses as if that server exists:

The mock server also has a few options to customize it:

--port to change the port from the default of 3000.
--watch to watch for file changes and reload when you modify the OpenAPI file.
--once to run tests once. Boots the server, responds to requests, and exits. Perfect for CI pipelines.

Why does OpenAPI mocking matter anyways?

Mock servers are more than just “fake APIs.” They unlock workflows that speed up development and reduce dependencies.

Parallel development: Frontend and backend teams can work independently without needing to wait for the real API to be built.
Testing without risk: Safely run tests and automations against the mock server without hitting production or staging (and the real errors that come with them).
Faster prototyping: Build and validate API contracts early in the process, before you’ve written any business logic.
Fewer third-party dependencies: Developers can work with third-party APIs without their rate limits, costs, and availability constraints.

A good mock server gives you confidence in the API while keeping the whole team moving.

How does Scalar’s OpenAPI mock server work under the hood?

Under the hood, the CLI relies on Scalar’s open source mock-server package to generate routes and serve requests.

The whole request flow looks like this:

The Scalar CLI detects whether your input is a file or URL then loads, dereferences, and validates it with the @scalar/openapi-parser package.
With the OpenAPI doc, the mock-server package generates routes for each path in Hono syntax and responses based on schemas. It also validates parameters, sets up authentication (if security schemes are defined), and returns appropriate HTTP status codes.
The generated routes are then served using Hono, a lightweight, fast HTTP framework. Hono is responsible for route matching, authentication checking, parameter extraction, and mock response generation.
The mock responses use Scalar’s open source oas-utils package to generate realistic data from OpenAPI schemas. This uses examples when available.
The generated data respects schema constraints like data types, formats, and validation rules to create mock responses that match your API specification.

All this gives you a fast, spec-compliant, developer-friendly mock server you can start in seconds.

Aug 19, 2025

How to do OpenAPI validation (and why it matters)

Mon, 07 Jul 2025 00:00:00 GMT

To validate your OpenAPI document, download the Scalar CLI:

npm -g install @scalar/cli

Note: There’s another scalar CLI which is bundled with Git. If you run into naming conflicts, but never use the other CLI anyway, you can replace it like this:
npm -g --force install @scalar/cli

Once installed, run the document validate command pointed at your OpenAPI document (no matter if it’s JSON or YAML).

scalar document validate galaxy.json

Now you have a validated OpenAPI document you can safely use however you like (or one that needs fixing 😅).

Fun fact: Scalar’s OpenAPI editor has validation built-in. No command line required.

Why does OpenAPI validation matter anyways?

Not sure why you’d do the above? You’ve come to the right place. The benefits of validating your OpenAPI doc include:

Prevents runtime errors and bad devex. Invalid or incomplete docs can result in confused users, broken test environments, incorrect references, and frustrated devs.
Ensures standards compliance. Tools in the OpenAPI ecosystem (like Scalar) often require your doc to fit the standard. Tools might reject your doc if invalid, or worse, break when you try to use an invalid one.
Enables automation. Automatically validating your OpenAPI doc unlocks automation elsewhere. You won’t need to manually upload the doc to generate mock servers, tests, codegen, and related areas of your CI/CD pipeline. All of it just works.
Catches breaking changes. If you have internal API standards, validating an OpenAPI doc against them can ensure these standards aren’t broken. This can be critical for proper API governance.

How does Scalar’s OpenAPI validation work?

Can’t get enough about OpenAPI validation, huh? Well here’s how it works under the hood.

We love two things at Scalar: open source and OpenAPI. This means we’ve built a bunch of tools to work with OpenAPI and they are all open source.

Most important for validation is the openapi-parser package. It is what the CLI is relying on to actually do the validation. Once you run the command, the process looks like this:

The parser loads the doc and ensures all $ref pointers are correctly resolved. These could be remote URLs needing fetching or local files needing to be read. It then replaces the references in the doc and creates a filesystem object containing the parsed doc.
It then checks the version then uses AJV (Another JSON Validator) to check against the official OpenAPI JSON schema. There is specific validation that happens for different versions of OpenAPI.
Once done, the CLI either returns a nice success message or transforms the AJV errors into a user-readable one.

All this is packaged into a simple to use CLI (with much more functionality). Also, because the openapi-parser is open source, if you wanted to implement (or modify) validation yourself, you could!

Jul 7, 2025

How we created an animated, responsive README

Wed, 28 May 2025 00:00:00 GMT

For an open source project, your README is your landing page. Using it to stand out makes a big impact on convincing developers to explore and adopt your tool. It is a window into your app (and you want users to enter it).

READMEs are written in Markdown, a format that is intentionally simple in its design. Usually, you are working with a very limited set of tools like text, bullet points, and images. Luckily, GitHub’s flavor of Markdown provides a lot more than people realize (like a lot of HTML being supported).

At Scalar, we take full advantage of this to create responsive and animated elements that make our README pop. Here’s all the details:

Creating responsive images

The Scalar app is responsive, why shouldn’t our images be? An API client or API reference has a ton of information included in it. For you to see all that detail, you need the right size of images. One size does not fit all.

Normal Markdown images only enable you to put one size. Even if we used the <img> HTML component, we’d still be in the same boat. SVGs on the other hand, enable us to do cool stuff like this:

This works by being an SVG with a <foreignObject> inside of it and <html> inside of that. The image remains centered in its container and is able to use CSS to control the display of the potential images. Here is a simplified example of how the code looks:

<svg xmlns="http://www.w3.org/2000/svg" width="100%" height="100%" viewBox="0 0 500 500">
  <foreignObject width="100%" height="100%">
    <div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: center; justify-content: center; height: 100%;">
      <img src="desktop-image.jpg" style="width: 100%; max-width: 400px;">
      <img src="mobile-image.jpg" style="width: 100%; max-width: 400px; display: none;">
      <style>
        @media (max-width: 450px) {
          img:first-of-type { display: none; }
          img:last-of-type { display: block; }
        }
      </style>
    </div>
  </foreignObject>
</svg>

And we didn’t just create one of these SVGs, we did two: one for light mode and the other for dark. Once you accept the fact that people use GitHub in light mode, you’ll probably not want to blind them with your images in the mode they choose.

Luckily, GitHub makes this a lot easier than responsive images. You simply need to add #gh-light-mode-only and #gh-dark-mode-only tags to add to the images like we do here:

	<img width="830" height="520" src="https://github.com/user-attachments/assets/7c4d4971-a6d9-457d-a7ab-11894889f6f9#gh-light-mode-only">
	<img width="830" height="520" src="https://github.com/user-attachments/assets/0e3ffca5-8912-487a-a390-fef0e8222c35#gh-dark-mode-only">

Adding Real ASCII in real Markdown

As a tool built for developers, we’re big fans of the ultimate art form of developers: ASCII. We use ASCII art in a bunch of places in our app, but unfortunately, Markdown doesn’t handle it well.

Instead, we use SVGs with foreign objects (again). This lets us do this:

As you can see, this enables three things:

Use ASCII in our README
Have a horizontal split for our two different products
Have both link to the correct spots

This is done with a combination of HTML (for the links) and SVGs that look like this:

<svg xmlns="http://www.w3.org/2000/svg">
    <foreignObject width="100%" height="100%"><script xmlns=""/>
        <div xmlns="http://www.w3.org/1999/xhtml" class="fixme">
            <div class="markdown-body">
                <pre class="markdown-code">

 +#INTRODUCING#.
 +#SCALAR##API#-
        -CLIENT-
      -TEST -UR-
    -FAV#   -##-
  -APIs     -##-
-LETS       -++-
.GO-
          </pre>
                <h3>API Client</h3>
                <p xmlns="http://www.w3.org/1999/xhtml">Offline first API Client <span class="mobile-copy"> built for
                        OpenAPI.</span></p>
                <p class="linkcolor">Download</p>
            </div>
            <style>
                * {
                    margin: 0;
                    padding: 0;
                    box-sizing: border-box;
                }

                .markdown-code {
                    font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
                    white-space: pre;
                    font-size: 0.5rem;
                }
                
                <!-- more styles... -->
            </style>
        </div>
    </foreignObject>
<script xmlns=""/></svg>

Creating animations that will knock your socks off

Now, all this is cool so far, but you could mistake it for any other GitHub repo. Something that would be totally unique to us is some sweet, sweet animations running in our GitHub repo.

We love our contributors. What better way to credit them than an animated shout out in our README? Contribution is a key piece of being open source after all. Again, we use SVGs and foreignobjects.

Our first iteration of this was a pillar in a room with each of our contributors projected on it.

This works by:

Creating “walls” using background textures and rotations.
Defining a 3D, rotating cube with ASCII-style avatars with commit info.
More ASCII art with usernames, number of commits, and line additions/deletions.
A CSS scroll animation to scroll this ASCII art continually upward

Eventually, we got bored of this and moved airplanes. The airplanes are HTML and they are animated with CSS.

This works by:

Creating two banners with the contributor name, commit count, and stats as well as the ASCII art of an airplane.
Using @keyframes, they move from left to right continuously at slightly different offset speeds.
The plane bounces continuously by repeatedly fading in and out of slightly different planes.
The banner contributor text and color change based on @keyframes as well.

Why not use a gif? Other than people not knowing how it is pronounced, gifs have worse performance and are honestly more difficult to make for developers used to coding animations by hand. Since we can show off our programming chops, why not do it?

Why all this work to make our README look cool?

It’s fun.
It makes us stand out.

When so many READMEs are the same, one that plays with the limits of it as a form really stands out. As an open source project reliant on our GitHub repo to attract and convince users, this makes a massive difference. We hope our experience will be helpful if you want to do the same.

May 28, 2025

How Scalar themes work

Wed, 07 May 2025 00:00:00 GMT

Every product can be thought of as a combination of three things: data, functionality, and display.

The beauty of API references is that they use a standardized data format (OpenAPI) to provide a massive amount of functionality for you. Building all this functionality would be a ton of work (and maintenance), but because it is similar between products, we can build it for you.

What’s not similar or standardized between products is display. Design matters a lot. You don’t want people thinking they’ve entered another product when they go to your API reference. Ideally, you want them to think you built all the functionality yourself.

We built themes to accomplish exactly this. They aim to make it easy to stylistically integrate our API references with your existing app (without breaking anything). This post covers how they work and how we built them.

Enabling smooth integrations through customization

The simplest way to customize your API reference is to use a pre-built theme. These include options like moon, solarized, saturn, mars, and more.

We’ve worked hard to make these options you want to use. For example, we’ve built a custom shadow system to work well in both light and dark modes.

Normal shadow systems use dark shadows on light backgrounds to create depth, but those same shadows look wrong on dark backgrounds.

To handle this, we use a subtler shadow with a higher spread in light mode and combine borders with shadows in dark mode. Both use multiple layers for natural depth while also integrating with theme CSS variables.

If you want to take the customization further, you can then dive into the CSS they are built with. These include light-mode and dark-mode options for details like text color, accents, font, background colors, spacing, and even the sidebar. All this can be edited in the web editor or directly using CSS variables and selectors.

For example, changing the font requires you to set the withDefaultFonts config option to false and then set it with the --scalar-font variable.

<!doctype html>
<html>
  <head>
    <!-- Link to the font on Google -->
    <link
      href="https://fonts.googleapis.com/css2?family=Roboto"
      rel="stylesheet" />
    <!-- Overwrite the Scalar font variable -->
    <style>
      :root {
        --scalar-font: 'Roboto', sans-serif;
      }
    </style>
  </head>
  <body>
    <!-- Pass the custom configuration object -->
    <script>
      var configuration = {
        theme: 'kepler',
        withDefaultFonts: 'false',
      }
    </script>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
  </body>
</html>

All this gives you the options to customize Scalar to your brand and integrate it stylistically.

Making customization easy for developers

The second part of themes is creating a great developer experience so you actually want to use it. As I hinted in the last section, this is largely done by providing clear variables and organization.

All variables:

Start with --scalar-.
Are grouped logically by function (color, typography, layout)
Clearly separated between light and dark mode

Beyond this, we also use a layer system to create conflict-free styling. The first layer is scalar-base which contains the core resets that normalize browser default styles and then sets the default styles for Scalar.

The second layer is scalar-theme which contains theme-specific styles and overrides. These are largely the variables you edit when you want to customize your theme.

The last piece of theme’s developer experience is providing tooling support like TypeScript support and a Tailwind preset that provides customer border radius values, border width configurations, color palette mapping, and more.

Oh, and we know it wouldn’t be good developer experience without a load of documentation and code examples for all things themes. We hope all this makes themes not only easy to customize, but enjoyable too.

Making sure themes don’t break anything

The last thing we want Scalar to do is break your app in unexpected ways.

Similar to the other two sections, this starts by scoping well. For themes, everything is scoped under the scalar-app class using the :where scoping. This is the first layer of defence to prevent unintended style leakage. The scalar-base and scalar-theme layers provide another and the light-mode and dark-mode one after that.

Another area that is liable to break is scrollbars. Unfortunately, macOS, Windows, and Linux all handle scrollbars differently. The ones on macOS don’t take up space, but the ones on Windows do. This means the spacing we worked so hard to get right can immediately get messed up.

To prevent this, we built a detection utility for obtrusive scrollbars that forces them to always be visible. It looks like this:

export function hasObtrusiveScrollbars(): boolean {
  if (typeof window === 'undefined') return false;

  // Create a 30px square div
  const parent = document.createElement('div')
  parent.setAttribute('style', 'width:30px;height:30px;overflow-y:scroll;')
  parent.classList.add('scrollbar-test')

  // Create a 40px tall child that forces scrolling
  const child = document.createElement('div')
  child.setAttribute('style', 'width:100%;height:40px')
  parent.appendChild(child)
  document.body.appendChild(parent)

  // If the child width is less than 30px, scrollbars are taking up space
  const firstChild = parent.firstChild as HTMLDivElement
  const scrollbarWidth = 30 - firstChild.clientWidth

  document.body.removeChild(parent)

  return !!scrollbarWidth
}

All of this helps developers gain confidence that Scalar will integrate with their existing setup and not break anything.

Themes are a core part of what makes Scalar work

Themes are a critical part of making Scalar a drop-in API reference solution that developers love. They enable us to provide all the functionality you’d want without your users realizing you didn’t build it.

Thanks to the customization options, developer tooling, and CSS structure, you can be confident that your API reference will look and feel like a natural extension of your product.

May 7, 2025

How Cloudinary’s API docs create a great developer experience

Mon, 28 Apr 2025 00:00:00 GMT

The first line on Cloudinary’s homepage is “Image and Video API Platform.” API is front and center as the primary way users interact with their app.

This API-focus enables Cloudinary to integrate into many more apps and use cases than other image and video tools, but it also means developers expect a world-class API experience.

A big part of that experience is the docs, tutorials, and videos helping people learn and use the API. Cloudinary shows how much you can do with these tools to make an API accessible. This post goes over their tactics.

Giving users multiple ways to get started

Every app cares about getting users onboarded and activated, and Cloudinary is no exception.

Cloudinary’s range of onboarding materials shows they know people learn differently, especially when it comes to programming. Some want a step-by-step video tutorial to walk them through building a sample app. Others just want straight access to the API. When you are trying to appeal to many types of users, you want to give many options to help them get started.

The full range of this getting started content which includes:

Quick starts: Simple tasks that teach the basics of programmatically optimizing, transforming, and managing images and video assets. These are written for both the API and SDKs.
Videos: Interactive video walkthroughs showing the core Cloudinary flows like how to upload assets, optimize images, cropping and resizing, and more.
Samples and examples: Examples with real, modifiable code you can test Cloudinary with. This provides users with an example they can edit to fit their use case.
Interactivity: The ability to test the API directly by sending requests to specific endpoints from the docs. Users can customize their requests, add their actual details, and get responses without needing to download or set up an API client or app.

By providing these options, users can self-select how they want to be taught. This helps them find a method that works for them, and makes it more likely they will succeed onboarding onto Cloudinary.

Supporting a diversity of use cases with OpenAPI

Although the getting started content is great, as users move beyond basic use cases, they fragment and become complex, but still require support.

Luckily, being API-first provides the flexibility to handle a diversity of use cases. Developers can integrate Cloudinary into their apps how they want, no pre-built components or complicated implementation patterns needed. This is awesome because it expands the potential market and user base.

To benefit from all the use cases (and help developers discover new ones), Cloudinary provides a full set of API documentation. They do this by relying on OpenAPI and Scalar. OpenAPI is a structured standard for describing APIs and Scalar uses it to display an API reference.

The great part about this combination is that OpenAPI is autogenerated, meaning Cloudinary doesn’t need to write a bunch of docs every time they add or change an endpoint. Scalar then regenerates the API reference based on the new OpenAPI document.

This enables users to discover the full range of Cloudinary’s capability and find the endpoints that fit their more complex and unique use cases.

The added benefits of OpenAPI and Scalar

Beyond covering many more use cases, the combination of OpenAPI and Scalar provides many benefits for Cloudinary and their users:

Functionality

An interactive API reference is basically an entire separate app. It requires:

An OpenAPI parser to make the data usable
A page generator for each of the endpoints
Components with each page to handle URLs, authentication, and examples
Templates for each example that need to work with specific client libraries
And all this needs to load fast, look nice, and be responsive

If teams had to do this themselves, they might default to a subpar experience: one that rapidly goes out of date, has poor performance, and doesn’t integrate with their existing website.

Scalar prevents this by making it as easy as possible to get a modern, stylish, and functional API reference. Cloudinary passes in an OpenAPI file to a script snippet and adds that to their site.

As a bonus, Cloudinary customizes Scalar using CSS selectors to fit their style and brand. Users likely won’t notice it's something they haven’t built themselves.

Interactivity

If that functionality didn’t impress you, Scalar built an entire API client into API references. This means users can send requests straight from Cloudinary’s docs, helping them get started without needing to build a sample app of their own.

Again, adding this sort of interactivity would take a significant amount of work and maintenance, but with Scalar, Cloudinary can provide this sort of best in class user experience easily.

Embracing the OpenAPI ecosystem

Scalar is just one example of a tool in the wider OpenAPI ecosystem. By standardizing on OpenAPI, Cloudinary (and its users) can benefit from all the progress happening in this ecosystem.

As an example, tools in this ecosystem can generate client SDKs (like Python or Ruby) from an OpenAPI document. These SDKs make setting up and using Cloudinary simpler and give another option for users with little added work for Cloudinary.

OpenAPI also helps make developers at Cloudinary more productive by:

Generating code like the SDKs mentioned above
Act as a source of truth for API functionality and purpose for internal and external stakeholders
Ensure API development best practices like consistent endpoint design and descriptions

It’s one thing to say you want to make APIs accessible, but it’s a lot of work to actually do it.

Cloudinary does a lot of this themselves, with their high quality docs and getting started guides, but also benefit from what’s being built in the OpenAPI ecosystem, like Scalar (and we’re happy to help 😎).

Apr 28, 2025

An introduction to OpenAPI variables

Wed, 23 Apr 2025 00:00:00 GMT

There are two types of OpenAPI variables:

Server variables: Strings used specifically in the server URL, primarily used for configuration.
Parameters: Potentially complex data types used to define data passed through the API.

This guide provides an overview of defining and using both.

Server variables

API requests need to go somewhere. That is what the URL defines. Server variables enable easy modification of the URL to support developer experience.

For example, if you had an app running on a strange port of a customer’s subdomain, you could define a customerId and port variable like this:

servers:
  - url: https://{customerId}.coolapp.com:{port}/v2
    variables:
      customerId:
        default: scalar
        description: Customer ID assigned by the service provider
      port:
        enum:
          - '443'
          - '8443'
        default: '443'

This helps developers on your team know the constraints of the URL as well as easily test multiple configurations of it.

Generally, server variables fit into one of the following use cases:

Configuring an API to work across dev, staging, and production environments
Testing APIs across both http and https protocols
Allowing flexibility in port selection
Defining subdomain values for customers, regions, or multi-tenant applications.

Parameters

Although not named variables, OpenAPI parameters function as variables in your OpenAPI document. They enable you to define data types and expectations for your API.

There are four main types of parameters:

Path, used in URL paths like /users/{id} to identify specific resources.
Query, added after a ? in the URL to optionally filter, sort, and paginate.
Header, sent in HTTP for metadata, auth tokens, and tracking.
Cookie, sent in the cookie header for things like session management, but generally avoided/not recommended.

For example, a basic parameter to get a specific user might look like this:

/users/{id}:
  get:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
          minimum: 5
        description: The ID for the user

For each parameter, you need to define its name, location (in), and data type (using schema or content). Beyond these, there are several other optional attributes like description and required.

Parameter attributes have many uses including:

Constraints including ones like maximum or minimum number values, string length and patterns, array uniqueness, and enum allowed values.
Validation including basic types like integer, data formats like int64, and complex objects (built of many constraints). This enables you to sanitize inputs and protect against attack vectors.
Defaults as well as defining whether null values are allowed with nullable: true.
Style and serialization definition AKA how arrays and objects are formatted in URLs and headers. For example, ids=[1,2,3] changes to:
- ?ids=1,2,3 when style: form
- ?ids=1%202%203 when style: spaceDelimited
- ?ids=1|2|3 when style: pipeDelimited
Content types like application/json, application/xml, application/x-www-form-urlencoded, text/plain, image/png, application/pdf, and their schemas.

For example, to represent a filter that accepts a JSON object with a name and (optionally) age that looks like this /api/endpoint?filter={"name":"John","age":25}, you can define the parameter like this:

parameters:
  - name: filter
    in: query
    content:
      application/json:
        schema:
          type: object
          required: [name]
          properties:
            name:
              type: string
              minLength: 1
            age:
              type: integer
              minimum: 0
          additionalProperties: false

Overall, parameters and their attributes provide a flexible way to create consistent and predictable APIs. They make APIs more approachable and understandable, especially when combined with an API reference and client tool like Scalar.

Reusing parameters

As a bonus, parameters can also be reused so you don’t need to define them multiple times. This is done by defining them in the components section like this:

components:
  parameters:
    ApiVersion:
      name: version
      in: header
      required: true
      schema:
        type: string
        enum: [v1, v2]
    PaginationLimit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20

Once done, you can reference them in your individual paths using $ref:

paths:
  /users:
    get:
      parameters:
        - $ref: '#/components/parameters/ApiVersion'
        - $ref: '#/components/parameters/PaginationLimit'

In a way, this is a sort of meta-level variable, a variable inside a variable.

The limitation of OpenAPI variables

Although OpenAPI provides a lot of flexibility for defining and using variables, it’s not close to providing everything you could ever want:

Server variables can only be strings and have limited validation options.
Parameters don’t support dynamic default values, computed values, or conditional values.
Parameter schemas don’t support custom validation functions, complex data structures for queries, and other advanced features.
Descriptions are limited to basic text limiting rich media, interactivity, and markdown.

Luckily, there’s no OpenAPI police going around preventing you from extending or changing how your document is written and processed. You can do whatever you want as long as you do the work to make the functionality work as you expect.

We know because this is exactly what we did when we added environment variables, code samples, internal controls, and more to our version of the OpenAPI specification, which you can read here.

Apr 23, 2025

How we extended the OpenAPI specification

Sun, 06 Apr 2025 00:00:00 GMT

We love OpenAPI, but as a team that develops a suite of tools built around it, sometimes we can find it limited. Luckily, because we control how the OpenAPI document is processed and displayed, we can do something about this.

We recently extended the OpenAPI specification with some features we wanted to see. This post is about what we added as well as how we made the changes under the hood to make them work.

What we added to the OpenAPI specification

At the moment, we have two main tools, our API reference and client. Our extensions to the OpenAPI specification are to support the experience we want to provide with both of these tools. Specifically, they include:

1. Environments

Our API client has the concept of environments which enables you to define environment variables and configurations for use across your endpoints. Collections can have multiple different environments.

You can set up an environment manually in the API client or you can set them up in your OpenAPI doc with x-scalar-environments like this:

# ... rest of your OpenAPI doc

x-scalar-environments:
  production:
    description: 'Production environment'
    color: '#0082D0'
    variables:
      apiKey:
        description: 'Production API Key'
        default: 'prod-key-123'

  development:
    description: 'Development environment'
    color: '#7ED321'
    variables:
      apiKey:
        description: 'Development API Key'
        default: 'dev-key-456'

This creates a pre-filled environment in the Scalar API client anytime someone imports the OpenAPI doc. This makes environments reusable and much easier to set up.

On top of that, you can specify which environment should be the default with x-scalar-active-environment. If you don’t set this, we just use the first x-scalar-environments value.

# ... rest of your OpenAPI doc

x-scalar-active-environment: development

2. Code samples

Although we provide a bunch of code samples for everything from cURL to http.client to clj-http, there might be more code samples you want to add to your API reference. This is where x-codeSamples comes in.

Each of these contains a label, programming language, and source code.

# ... rest of your OpenAPI doc

paths:
  /upload:
    post:
      summary: Upload a file
      description: Uploads a file to the server with optional metadata
      x-codeSamples:
        - lang: Python
          label: Python SDK
          source: |
            import mycompany_sdk

            client = mycompany_sdk.Client("YOUR_API_KEY")

            # Upload file with metadata
            response = client.upload_file(
                file_path="example.pdf",
                metadata={"category": "documents"}
            )
            print(response.file_id)

      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                metadata:
                  type: object
                  properties:
                    category:
                      type: string
      responses:
        '200':
          description: File uploaded successfully

This then will show up as the sample for the operation in Scalar’s API reference.

x-codeSamples are great for providing SDK examples, complex operations, language-specific features, and more.

3. Tags

Tags are used to group similar operations.

The trouble with tags is that they can have one use internally and a different usage externally. For example, you might have legacy, technical, or abbreviated tags internally, but want a different tag name to show externally.

To handle this, we added the x-displayName attribute. This overwrites the tag name in the OpenAPI doc with a new one users will see in the API reference. For example, to change the tag name pets_v1 to Pets, you can do this:

tags:
  - name: pets_v1
    x-displayName: Pets # This will display as "Pets" instead of "pets_v1"
    description: Pet management operations

On top of this, larger OpenAPI docs often have a lot of unorganized tags and endpoints. We provide

x-tagGroups:
  - name: Store Management
    tags:
      - stores_v1
      - inventory_v1
  - name: Pet Operations
    tags:
      - pets_v1
  - name: Human Resources
    tags:
      - employees_v1

4. Internal

Because your OpenAPI doc might include endpoints you don’t want published, we can help hide them from the API reference and client using

/system/cache/clear:
  post:
    summary: Clear system cache
    description: Internal endpoint to clear the application cache
    x-internal: true
    responses:
      '200':
        description: Cache cleared successfully

5. Additional properties

Finally, a little quality of life improvement for additional properties. Although normal properties have known fixed names, additional properties do not. If you’d like to add a name, you can use

MetadataObject:
  type: object
  properties:
    createdAt:
      type: string
      format: date-time
  additionalProperties:
    x-additionalPropertiesName: metadataField
    type: object
    description: Dynamic metadata fields

How we handle these under the hood

The work to handle this extended OpenAPI spec and make it actually do something in Scalar’s API client and reference requires schema validation, integration with our store, and UI implementation.

1. Schema validation

Each parameter or attribute is handled in a similar way under the hood. They all start with a schema defined using Zod validation. This ensures the OpenAPI doc matches the expected structure, fields are present and have correct types, and optional fields are handled correctly.

export const xScalarEnvironmentSchema = z.object({
  description: z.string().optional(),
  color: z.string().optional(),
  variables: z.record(z.string(), xScalarEnvVarSchema),
})

When we change the schema, we don’t want to break past versions of the schema. To prevent this, we set up and run some migrations. We store the version and types for that version and then the migrator helps change versions. For example, the migration to add x-scalar-environments looked like this:

export const migrate_v_2_3_0 = (data: v_2_2_0.DataRecord): v_2_3_0.DataRecord => {
  // Other migration logic...

  const collections = Object.values(data.collections).reduce
    v_2_3_0.DataRecord['collections']
  >((prev, c) => {
    prev[c.uid] = {
      ...c,
      'x-scalar-environments': c['x-scalar-environments'] || {},
    }
    return prev
  }, {})
  // ... rest of your code

2. State management

The schema then integrates with the relevant store and its associated mutators. For example, x-scalar-environments integrates with the store responsible for environment handling like this:

// Handles active state for environments and collections
export const createActiveEntitiesStore = ({
  collections,
  requestExamples,
  requests,
  router,
  workspaces,
}) => {
  // Environment handling
  const activeEnvironment = computed(() => {
    if (!activeWorkspace.value.activeEnvironmentId) {
      return {
        uid: '',
        name: 'No Environment',
        value: JSON.stringify(activeWorkspace.value.environments, null, 2),
      }
    }

    // Find environment in collections
    const activeEnvironmentCollection = activeWorkspaceCollections.value.find(
      (c) => c['x-scalar-environments']?.[activeWorkspace.value.activeEnvironmentId]
    )
    // ...

3. UI implementation

Finally, with the data validated and integrated with the stores, we can change the UI that users actually see. The only hang up here is that each extension ends up affecting a different part of Scalar: some only impact the API client, others only the API reference.

On top of this, the complexity varies dramatically:

x-displayName, x-tagGroup, x-internal, x-additionalPropertiesName are all relatively straightforward conditional rendering.
x-codeSamples integrates with the existing code sample code.
The most complicated is x-scalar-environments which integrates with multiple different components including all of the ones necessary to create, select, and edit environments as well as variable substitution in requests and more.

In the end, most of what you see is small improvements to the overall experience of using OpenAPI docs with Scalar’s API client and reference. This is the point. We know these small improvements add up to create the best possible experience for API developers.

Why extend the OpenAPI specification?

Extending the OpenAPI specification enables us to continue to use OpenAPI documents as the source of truth while providing improved developer experience, better configuration management, and improved organization. Expect to see more extensions from us in the future as we build out our tools to work with OpenAPI.

Apr 6, 2025

A guide to OpenAPI security (and how we handle it in Scalar)

Wed, 26 Mar 2025 00:00:00 GMT

Just like the real world, there are often areas of your code you want to protect and you set up security to protect them. Unlike the real world, it’s often not obvious how to interact with these security mechanisms, especially when it comes to APIs.

This is where defining security in OpenAPI documentation comes in. This enables you to define the authentication and authorization mechanisms you’ve put into place. This helps the users of your API understand security requirements and interact with protected parts of your API in the right way.

This post details the types of security, how to define them in your OpenAPI doc, and how they work in Scalar’s API reference and client.

What about security definitions? This was the name of the same concept security schemes in OpenAPI 2 (formerly Swagger).

The many types of security for OpenAPI docs

OpenAPI documents are representations of real APIs and those real APIs have many different ways of securing their data. The types of security you can define include:

API keys: These can be sent in headers, query parameters, or cookies.
HTTP: This includes both basic username and password as well as bearer tokens. You can also define the bearerFormat such as JWT.
OAuth 2.0: Supports multiple types of authorization flows, from standard redirect-based to direct sign-in to application-level. Each flow can define where to request authorization, where to exchange codes for tokens, and available permissions.
OpenID Connect: Finally, OpenID builds on top of OAuth 2.0. It allows clients to automatically get configuration information using a “well-known” discovery endpoint.

Each of these can be combined using AND/OR logic. They can also be applied globally or per-operation.

How to define OpenAPI security

Defining your OpenAPI security starts by adding the securitySchemes property. This defines all the security schemes your API supports. You then use security to apply the schemes globally or per-operation.

You can think of securitySchemes like the ID types available (passport, driver’s license, badge) while security specifies which IDs are required to enter.

For example, if you want to include either BasicAuth or ApiKeyAuth anywhere in your OpenAPI doc, it starts by defining them as securitySchemes:

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

With securitySchemes defined, you can then apply them at the global level by adding security like this:

security:
  - ApiKeyAuth: []
  - BasicAuth: []

components:
  securitySchemes:
# ... rest of your OpenAPI doc

With security set up, you can define your securitySchemes. This can apply to individual operations or globally. For example, to apply BasicAuth globally, you OpenAPI file would look like this:

security:
  - BasicAuth: []

components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: Basic Authentication using username and password
# ... rest of your OpenAPI file

To apply it to a single operation, define the security property on the path like we do here:

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for protected endpoints

paths:
  /orders:
    post:
      summary: Create new order
      description: Protected endpoint - requires API key
      security:
        - ApiKeyAuth: [] # This operation requires API key
      responses:
        '201':
          description: Order created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: integer
                  status:
                    type: string
        '401':
          description: Unauthorized - invalid or missing API key
  # ... rest of your OpenAPI file

Each security scheme also has different properties beyond type and the optional description you can define. For example:

apiKey has in and name
http has scheme and bearerFormat
oauth2 has flows which has authorizationCode, implicit, and password each with their own properties
OpenIdConnect has openIdConnectUrl

Of course, the flip side of all of this is that the OpenAPI doc is just a representation of your actual underlying API. You need to actually implement the security.

Defining security with your framework

A nice thing about modern API development frameworks is that they generate OpenAPI docs for you. This also means that they provide easy ways to define security for your API. Here’s an example for Hono:

// Register the security scheme in your OpenAPI docs
app.openAPIRegistry.registerComponent('securitySchemes', 'Bearer', {
  type: 'http',
  scheme: 'bearer',
  description: 'Enter your JWT token in the format: Bearer <token>',
})

// Apply the security to your routes
const route = createRoute({
  method: 'get',
  path: '/protected-resource',
  security: [{ Bearer: [] }],
  handler: async (c) => {
    const token = c.req.header('Authorization')
    // Token validation logic here
    return c.json({ message: 'Protected data' })
  },
})

And to add JWT authorization to a .NET API:

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen(options => {
    options.AddSecurityDefinition("Bearer", new OpenApiSecurityScheme {
        Type = SecuritySchemeType.Http,
        Scheme = "bearer",
        BearerFormat = "JWT",
        Description = "JWT Authorization header using the Bearer scheme. Example: 'Bearer {token}'"
    });

    options.AddSecurityRequirement(new OpenApiSecurityRequirement {{
        new OpenApiSecurityScheme {
            Reference = new OpenApiReference {
                Type = ReferenceType.SecurityScheme,
                Id = "Bearer"
            }
        },
        Array.Empty<string>()
    }});
});

// Apply authentication to your endpoints
app.MapGet("/protected", [Authorize] () => "This endpoint requires authentication")
   .WithOpenApi();

And finally, for FastAPI:

from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials
import secrets

app = FastAPI(
    title="Protected API",
    description="API secured with HTTP Basic Auth"
)

security = HTTPBasic()

def verify_credentials(credentials: HTTPBasicCredentials = Depends(security)):
    # In production, use secure password comparison
    correct_username = secrets.compare_digest(credentials.username, "admin")
    correct_password = secrets.compare_digest(credentials.password, "secret")

    if not (correct_username and correct_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

@app.get("/secure-data/",
    summary="Get protected data",
    responses={
        401: {"description": "Invalid credentials"},
        200: {"description": "Successfully authenticated"}
    })
def secure_data(username: str = Depends(verify_credentials)):
    return {"message": f"Hello, {username}"}

This is where it really pays off to have a framework that generates the OpenAPI doc (well) for you. For example, Django doesn’t generate an OpenAPI doc automatically, making interacting with it for API reference or debugging a lot harder.

How Scalar handles security

The whole point of defining a security scheme is that it makes using an API easier. This means API references and clients need to handle the many security schemes OpenAPI provides.

API reference

Our API reference supports API key, HTTP, and OAuth 2.0 security schemes. Based on your OpenAPI document and the security schemes applied to your operations, users can choose one of these and send requests with it.

Behind the scenes, we handle the logic for applying the correct scheme for each operation, include the UI to gather the needed information, set up the correct auth method on users’ requests, handle state for the auth, and handle errors that come from invalid credentials or other auth failures.

API client

The API client looks very similar. The big difference is that because your client state can be private to you, we can store it between sessions and collections. This also means you might have multiple collections as well as multiple active security schemes.

To handle this, we store auth values at the collection-level, support operation-level overrides, and allow you to select the scheme you want on per-request. The selectors for schemes are also more interactive, allowing editing of API key name fields and scheme deletion.

Our API client also pre-fills as much information as possible. It auto detects security schemes, creates default value structures based on scheme types, pre-configs OAuth flows if provided, and more.

Supporting API security and developer experience

As with many areas of Scalar, we continue to improve the connection between your OpenAPI doc, API reference, and API client. For example, we recently added the ability to sync authentication settings between the API reference and the API client. The API reference can pass auth settings to the client modal and the select security schemes become the default in the client.

Security shouldn’t come at the cost of developer experience. The tools Scalar provides help developers authenticate quickly and correctly. This helps them test endpoints, debug, and ultimately build better (and more secure) APIs.

Mar 26, 2025

The hidden complexity of building drag and drop

Wed, 19 Mar 2025 00:00:00 GMT

When we rearrange things in the real world, we pick them up and put them down. Picking something up, moving it, and putting it down is the pattern we unconsciously rely on.

Users expect that same pattern to work in the apps they use. Unfortunately for those who have to implement this, gravity isn’t built into computers. Writing all the logic needed to drag and drop in an app is a lot of work.

We know because we recently had to go through all this work when building drag and drop into our API client. This post shows off what we built and all the work under the surface to make it happen.

What can you drag and drop in Scalar’s API client?

Most obviously, you can move and rearrange the three main objects in our API client: collections, folders, and requests. The last two can be dragged and dropped between folders, into folders, and out of folders.

On top of this, drag and drop can be used to import OpenAPI docs. This can be done both by dragging in .yml, .yaml, and .json files as well as URLs.

What’s so tricky about drag and drop?

Creating a slick drag and drop experience required us to solve the following challenges:

Where. You can’t drag everything everywhere. Only certain objects can be dropped into certain spots. This means you need validation and visual feedback like drop zones, UI updates, cancellation, and error handling.
State management. Both dragging and dropping needs to work with the many levels of state the API client has including collections, folders, and requests as well as their parent-child relationships. The UI aspects like collapsed versus expanded also need to be handled.
Performance. When you drag an element, your browser fires dragover events many times per second. If you don’t throttle these, you run potentially expensive calculations like determining drop zones, calculating positions, updating UI indicators on every single mouse movement. This can create UI jitters or lag your entire app.
Context. Requests and collections aren’t simple. They include information on authentication settings, examples, test cases, response history, security schemes, and servers. Behind this is a structured OpenAPI document that needs to stay valid.

How does our API client handle drag and drop challenges?

Rather than existing libraries like react-dnd, vue-draggable, we developed our own @scalar/draggable package with a Draggable.vue component. To make dragging and dropping consistent across the API client, the component uses standard HTML 5 drag and drop APIs to:

Track dragging and hovering state
Handle drag events
Provide visual feedback
Customize drop zones
Track hierarchy for validation

Here’s how we specifically handle some of the challenges with dragging and dropping we identified:

Validation

The Draggable.vue component enables us to define droppable checks unique to each component and object type. For example, requests and folders can’t be dropped in lower-level containers, they can’t receive drops, and they can’t be read only:

// RequestSidebarItem.vue
const _isDroppable = (draggingItem, hoveredItem) => {
  if (activeWorkspace.value.isReadOnly) return false
  if (requestExamples[hoveredItem.id]) return false
  if (collections[draggingItem.id]) return false // Collections can't be dropped anywhere
  return true
}

Collections can be reordered but not dropped in “Drafts”, can receive requests and folders as dropped but only as children, and can’t be read only:

// Request.vue (for collections)
const _isDroppable = (draggingItem, hoveredItem) => {
  if (activeWorkspace.value.isReadOnly) return false
  if (!collections[draggingItem.id] && hoveredItem.offset !== 2) return false // Requests/folders must be dropped AS CHILDREN
  if (
    collections[draggingItem.id] &&
    collections[hoveredItem.id]?.spec?.info?.title === 'Drafts'
  )
    return false
  return true
}

The Draggable.vue component also has hierarchy validation to ensure an object isn’t highlighted if hovering over itself or child. It also has configurable position-based validation.

const getDraggableOffsets = computed(() => {
  let ceiling = 0.5
  let floor = 0.5

  // If hovered over is collection && dragging is not a collection
  if (!collections[draggingItem?.id] && isCollection.value) {
    ceiling = 1
    floor = 0
  }
  // Has children but is not a request or a collection
  else if (hasChildren.value && !isRequest.value && !isCollection.value) {
    ceiling = 0.8
    floor = 0.2
  }

  return { ceiling, floor }
})

All of this is implemented through props passed down to the draggable component. This ensures that the Draggable component is scoped to only the drag and drop logic it needs to handle and makes it more reusable.

Visual feedback

We provide feedback at 3 spots for dragging and dropping:

Above. Uses the dragover-above class to show feedback when hovering above an item.
Below. Uses the dragover-below class to show feedback when hovering below an item.
As a child. Uses the dragover-asChild class when hovering to nest inside an item.

Both above and below a 3px blue semi-transparent line either above or below the item. For nesting, we highlight the entire target with a semi-transparent blue overlay.

Beyond this, there are a few styling things we do to make this look good. The styles are implemented using CSS pseudo-elements (:after), we use pointer-events: none to ensure indicators don’t interfere with drag operations, and use CSS color-mix() to create a subtle, semi-transparent effect that matches the UI theme.

Performance

Because the dragover event fires extremely frequently and is tied to position and visual calculations, it can cause UI jitter or lag. To prevent this, we built a throttle function that:

Limits the dragover handler to firing at most once every 25 milliseconds (40 times per second)
Drops intermediate events during that 25ms window
Still ensures enough updates to maintain smooth visual feedback

This function looks like this:

export const throttle = <T extends (...args: any[]) => void>(
  func: T,
  limit: number,
): T => {
  let inThrottle: boolean
  let lastResult: any

  return ((...args) => {
    if (!inThrottle) {
      inThrottle = true

      lastResult = func(...args)

      setTimeout(() => {
        inThrottle = false
      }, limit)
    }

    return lastResult
  }) as T
}

It takes a function and a time limit, returns a wrapped version that only executes once within the time window, and tracks whether we’re still in the throttle.

This is enough to provide smooth (40 fps) animations while still significantly reducing the processing overhead of raw dragover events.

State management

The core Draggable.vue component doesn’t handle state, only hover positions as well as drag start and end events with that position information.

The actual state management is lifted to the parent component Request.vue. This prevents drops in read-only mode, handles collection-specific rules, and manages the hierarchical relationship between collections, folders, and requests. It also handles different mutation types depending on the target.

const mutate = (uid: string, childUids: string[]) => {
  if (collections[uid]) collectionMutators.edit(uid, 'childUids', childUids)
  else if (folders[uid]) folderMutators.edit(uid, 'childUids', childUids)
}

This structure isolates drag and drop from our business logic, ensures we handle OpenAPI document validity constraints, and provides us the flexibility to add new drag and drop rules without modifying the base component.

The undersurface complexity of drag and drop

Although drag and drop seems simple on the surface, there is a lot of complexity to make it work nicely. It required us to handle OpenAPI document validation, performance, visual feedback, hierarchy, and state management.

This is representative of one of many of the little optimizations we do to try to make working with APIs as easy as possible.

Mar 19, 2025

How we sped up our API docs 25x

Wed, 12 Mar 2025 00:00:00 GMT

API docs have a unique structure compared to other types of documentation. They have many related pages which need to be easily accessible from each other. This can mean a lot of menu items.

Our users pushed this to the limit, and it was showing. They were uploading 7+ MB OpenAPI documents, some with 30+ groups, 10+ endpoints per group, and 50+ models. This was causing significant performance issues, something we know developers (the users of an API) are particularly sensitive about.

Diagnosing our performance issues

The obvious first spot to look at is how data is imported into the client.

To check this, Amrit sprinkled console.time and console.timeEnd calls around the relevant methods. (Un)fortunately, they were fine, and he moved on to checking for issues after the data was imported and set up.

Next, he experimented by commenting out chunks of the UI until he saw load times dramatically decrease. This is how he discovered the culprit component: the Request Sidebar.

By timing the onBeforeMount and onMounted hooks, he found that a 7 MB OpenAPI spec took 2.6 seconds to mount (way too long). Narrowing down, it was specifically the Request Sidebar Item that was causing the issue.

Each instance of RequestSidebarItem created multiple child modals and menus. These made it easy for editors to rename and delete items, but, when repeated across hundreds of sidebar items, were causing major slowdowns.

Refactoring our sidebar to fix the performance issues

Fixing this required us to rework how users edit sidebar items.

To start, Amrit hoisted the edit and rename modals outside of RequestSidebarItem to ensure they were only created once. He also decided that the context menu was doing more harm than good. It enabled users to right-click to edit but didn't add functionality beyond what was already there, so he removed it.

The trickiest fix was the dropdown menu. headlessui, a component library we use, makes it harder to open the menu when the triggering button wasn’t a child of the component. This is why the menu was repeated inside every instance of RequestSidebarItem; we needed the ... button to open it.

Opening this menu in the right spot required:

Passing a targetRef to both the floating popup and dropdown menu.
Targeting the menu on the parent element because the button to open the menu only appeared on hover. This was resetting the position of the floating menu.
Manually focusing on the dropdown menu once opened and setting up a global click listener to close it.

Maintaining functionality while improving performance

Most users probably didn't notice changes to the sidebar functionality. It looks the same and works the same.

What users with large API docs will notice is a dramatic performance improvement. Thanks to these fixes, loading times for a 7 MB OpenAPI doc improved 25x, going from 2.6s to 0.11s.

Improving performance is a continual process. For example, immediately after this, we upgraded to Vue 3.5, which came with reactivity system optimizations. As a company building for developers, we know how important performance is, so expect these improvements to continue.

Mar 12, 2025

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

Wed, 05 Mar 2025 00:00:00 GMT

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 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 an 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 turns 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.

Mar 5, 2025

Scalar Joins the Open-Source Pledge

Sun, 01 Sep 2024 00:00:00 GMT

Sep 1st, 2024

What is OSS Pledge?

You can read more about it here, but in short, it's paying Open Source maintainers. The minimum to participate is $2,000 per full-time employed developer per year.

When we met Chad Whitacre at the Open-Source Summit in Seattle earlier this year, we instantly bonded over all things open-source! He also told me about the very early stages of the Open-Source Pledge that Sentry was starting and I couldn't have been more excited about joining it.

@getsentry & @scalar love open-source!

w @__chadwhitacre @linuxfoundation #OSSummit

@marclaventure on X

How much Scalar Gives

We have donated $25,569.34 USD so far in 2024, which equates to $3,652.76 USD per Scalar Employee. Here is a list of who we donate to on a monthly basis and single donations for open-source foundations:

litestar-org $250/month (LiteStar)
SaltyAom $300/month (ElysiaJS)
colinhacks $99/month (Zod)
tiangolo $500/month (FastAPI)
yusukebe $100/month (Hono)
marijnh $5/month (CodeMirror/ProseMirror)
daveshanley $100/month (libopenapi)
LinusBorg $5/month (Vue.js Maintainer)
pi0 $31/month (Nuxt/UnJS)
dmonad $10/month (YJS)
thibaultleouay $10/month (OpenStatus)
fuma-nama $10/month (FumaDocs)
litestar + python (3,529.34)
algoria OSS Bounty TypeScript Challenge + Daniel Roe (5,000)

Thank You OSS

Most of the team at Scalar have started their Engineering careers because of Open-Source, and we couldn't be more honoured to be a part of the OSS Pledge! Thanks to all the maintainers and contributors whose software we are privileged to use and build with.

Marc, CEO & co-founder, Scalar

Scalar Blog

OpenAPI with NestJS

Install and bootstrap

Which OpenAPI version you get

Why DTOs need help

Decorators by hand

The CLI plugin

Describe responses explicitly

Make operation IDs stable

Authentication

Mapped types: import from the right package

Enums, generics and extra models

Export the document for CI

Common mistakes

What to do with the document

Frequently asked questions

Related

OpenAPI with FastAPI

How FastAPI builds the document

The minimum app

Describe the API, not only the types

App-level metadata

Per-operation metadata

Document every response, not only the happy path

Parameters and fields

Make operation IDs stable

Authentication

Input and output schemas

Webhooks

Customize the whole document

Export the document for CI

Common mistakes

What to do with the document

Frequently asked questions

Related

OpenAPI with ASP.NET Core in .NET 9 and 10

Why Swashbuckle stopped being the default

.NET 9 vs .NET 10 at a glance

Add OpenAPI generation

Choose the OpenAPI version

Serve JSON, YAML, or both

Describe your endpoints properly

Return typed results

Add summaries, descriptions, tags and operation IDs

Let the models describe themselves

Use XML comments (.NET 10)

Customize the document with transformers

Upgrading transformers from .NET 9 to .NET 10

Generate several documents

Generate the document at build time

Common mistakes

What to do with the document

Frequently asked questions

Related

Migrating off Stainless: week-one checklist

The week at a glance

Day 1: Inventory what you actually ship

Day 2: Snapshot the public surface

Day 3: Find every credential, app and workflow

Day 4: Build a compatibility harness

Day 5: Put guardrails on the API and tell your team

What not to do in week one

Where to go next

Frequently asked questions

Related

Release notes: 19–26 September 2026

Versions released this week

OpenAPI 3.2 support

New in the API reference

New in the API client

Performance

Fixes

Security hardening

Elsewhere in the monorepo

Upgrade notes

Related

We wrote up the Stainless wind-down

Scalar's 2025 Open Source Pledge

Too Long; Didn't Read; Used MCP

Use your API in Cursor