Scalar API Reference

Generate interactive API documentation from OpenAPI/Swagger files. Try our Demo

Features

Uses OpenAPI/Swagger specifications
Request examples for a ton of languages + frameworks
Has an integrated API client
Edit your OpenAPI/Swagger specification with a live preview
Doesn’t look like it’s 2011

Note

Scalar Townhall every 2nd Thursday in Discord

Join us to see upcoming features, discuss the roadmap and chat about APIs. 💬

Getting Started

From a CDN

<!doctype html>
<html>
  <head>
    <title>Scalar API Reference</title>
    <meta charset="utf-8" />
    <meta
      name="viewport"
      content="width=device-width, initial-scale=1" />
  </head>
  <body>
    <!-- Add your own OpenAPI/Swagger specification URL here: -->
    <!-- Note: The example is our public proxy (to avoid CORS issues). You can remove the `data-proxy-url` attribute if you don’t need it. -->
    <script
      id="api-reference"
      data-url="https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml"
      data-proxy-url="https://api.scalar.com/request-proxy"></script>

    <!-- Optional: You can set a full configuration object like this: -->
    <script>
      var configuration = {
        theme: 'purple',
      }

      document.getElementById('api-reference').dataset.configuration =
        JSON.stringify(configuration)
    </script>
    <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
  </body>
</html>

You can also use the following syntax to directly pass an OpenAPI specification:

<script
  id="api-reference"
  type="application/json">
  { … }
</script>

If you’d like to add a request proxy for the API client (to avoid CORS issues):

<script
  id="api-reference"
  type="application/json"
  data-proxy-url="https://api.scalar.com/request-proxy">
  { … }
</script>

Events [beta]

We have recently added two events to the standalone CDN build only.

scalar:reload-references

Reload the references, this will re-mount the app in case you have switched pages or the dom elements have been removed.

document.dispatchEvent(new Event('scalar:reload-references'))

scalar:update-references-config

If you have updated the config or spec, you can trigger this event with the new payload to update the app. It should update reactively so you do not need to trigger the reload event above after.

import { type ReferenceProps } from './types'

const ev = new CustomEvent('scalar:update-references-config', {
  detail: {
    configuration: {
      spec: {
        url: 'https://cdn.scalar.com/spec/openapi_petstore.json',
      },
    },
  } satisfies ReferenceProps,
})
document.dispatchEvent(ev)

With Nuxt

You can easily run Scalar API References in Nuxt via the module:

npx nuxi module add @scalar/nuxt

If you are using Nuxt server routes, you can enable scalar simply by enabling openAPI in the nitro config in your nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  nitro: {
    experimental: {
      openAPI: true,
    },
  },
})

If you would like to add your own OpenAPI spec file, you can do so with the following minimal config:

export default defineNuxtConfig({
  modules: ['@scalar/nuxt'],
  scalar: {
    spec: {
      url: 'https://cdn.scalar.com/spec/openapi_petstore.json',
    },
  },
})

With Vue.js

The API Reference is built in Vue.js. If you’re working in Vue.js, too, you can directly use our Vue components. Install them via npm:

npm install @scalar/api-reference

And import the ApiReference component to your app:

<script setup lang="ts">
import { ApiReference } from '@scalar/api-reference'
</script>

<template>
  <ApiReference />
</template>

You can pass props to customize the API reference.

With React

The API Reference package is written in Vue, that shouldn’t stop you from using it in React though! We have created a client side wrapper in React:

Warning

This is untested on SSR/SSG!

import { ApiReferenceReact } from '@scalar/api-reference-react'
import React from 'react'

function App() {
  return (
    <ApiReferenceReact
      configuration={{
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
        },
      }}
    />
  )
}

export default App

export default App


### With Next.js

Our Next.js handler makes it easy to render a reference; just add it to an API
route handler:

```ts
// app/reference/route.ts
import { ApiReference } from '@scalar/nextjs-api-reference'

const config = {
  spec: {
    url: '/openapi.json',
  },
}

export const GET = ApiReference(config)

With Fastify

Our fastify plugin makes it so easy to render a reference, there’s no excuse to not have documentation for your API:

await fastify.register(require('@scalar/fastify-api-reference'), {
  routePrefix: '/reference',
  configuration: {
    spec: () => fastify.swagger(),
  },
})

Actually, it’s executing the fastify.swagger() call by default (if available). So that’s all you need to add:

await fastify.register(require('@scalar/fastify-api-reference'), {
  routePrefix: '/reference',
})

We wrote a detailed integration guide for Fastify, too.

Read more about the package: @scalar/fastify-api-reference

With Platformatic

Good news: If you’re using a recent version of Platformatic, the Scalar API reference is installed and configured automatically.

With Hono

Our Hono middleware makes it so easy to render a reference:

import { apiReference } from '@scalar/hono-api-reference'

app.get(
  '/reference',
  apiReference({
    spec: {
      url: '/openapi.json',
    },
  }),
)

With ElysiaJS

The @elysiajs/swagger plugin uses our API reference by default:

import { swagger } from '@elysiajs/swagger'
import { Elysia } from 'elysia'

new Elysia()
  .use(swagger())
  .get('/', () => 'hi')
  .post('/hello', () => 'world')
  .listen(8080)

// open http://localhost:8080/swagger

With Express

Our Express middleware makes it so easy to render a reference:

import { apiReference } from '@scalar/express-api-reference'

app.use(
  '/reference',
  apiReference({
    spec: {
      content: OpenApiSpecification,
    },
  }),
)

With NestJS

Our NestJS middleware makes it so easy to render a reference:

import { apiReference } from '@scalar/nestjs-api-reference'

app.use(
  '/reference',
  apiReference({
    spec: {
      url: '/openapi.json',
    },
  }),
)

With Docusaurus

Our Docusaurus plugin makes it easy to render API references. Simple add the following to your Docusaurus config:

import type { ScalarOptions } from '@scalar/docusaurus'

plugins: [
  [
    '@scalar/docusaurus',
    {
      label: 'Scalar',
      route: '/scalar',
      configuration: {
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
        },
      },
    } as ScalarOptions,
  ],
],

For more information, check out the Docusaurus package

With AdonisJS

There’s a community package to generate OpenAPI files in AdonisJS, and it comes with support for the Scalar API reference already.

We wrote a detailed integration guide for AdonisJS.

With Laravel

There’s a wonderful package to generate OpenAPI files for Laravel already. Set the type to external_laravel (for Blade) or external_static (for HTML) and theme to scalar:

<?php
// config/scribe.php

return [
  // …
  'type' => 'external_laravel',
  'theme' => 'scalar',
  // …
];

We wrote a detailed integration guide for Laravel Scribe, too.

With Rust

There’s a wonderful package to generate OpenAPI files for Rust already. Set the api_route to use Scalar to get started:

use aide::{
    axum::{
        routing::{get_with},
        ApiRouter, IntoApiResponse,
    },
    openapi::OpenApi,
    scalar::Scalar,
};
...
    let router: ApiRouter = ApiRouter::new()
        .api_route_with(
            "/",
            get_with(
                Scalar::new("/docs/private/api.json")
                    .with_title("Aide Axum")
                    .axum_handler(),
                |op| op.description("This documentation page."),
            ),
            |p| p.security_requirement("ApiKey"),
        )
        ...

CLI

We’ve also got a nice command-line interface that you can use to play with OpenAPI files locally, integrate validation into your CI or share them easily (with us or anyone else).

CLI documentation

Here are a few use cases:

Installation

You can use npx to use the CLI without manually installing it:

npx @scalar/cli --version

If you want to install it locally, you can do it like this:

npm -g install @scalar/cli
scalar --version

Format

Quickly bring your OpenAPI file (JSON or YAML) into shape:

scalar format openapi.json --output openapi.yaml

Validate

Validate your OpenAPI file to find errors quickly, great for CI:

scalar validate openapi.json

Oh, and all commands work with hosted OpenAPI files, too:

scalar validate https://example.com/openapi.json

Preview

Preview the API reference for your OpenAPI file with just one command. It can even watch your file and reload the content on file changes:

scalar reference openapi.json --watch

Mock server

Designing an API, but don’t have a backend yet? Just quickly boot up a mock server like this:

scalar mock openapi.json --watch --port 8080

Want to share your OpenAPI file? It’s as easy as this:

scalar share openapi.json

Hosted API Reference

Wait, this is open source and you can do whatever you want. But if you want to add a nice, customizable guide, collaborate with your team and have everything served through a CDN, create an account on scalar.com.

Configuration

To customize the behavior of the API Reference, you can use the following configuration options:

spec.content: Directly pass an OpenAPI/Swagger specifcation.
spec.url: Pass the URL of a spec file (JSON or YAML).
proxyUrl: Use a proxy to send requests to other origins.
darkMode: Set dark mode on or off (light mode)
layout: The layout to use, either of modern or classic (see #layouts).
theme: The theme to use (see #themes).
showSidebar: Whether the sidebar should be shown.
customCss: Pass custom CSS directly to the component.
searchHotKey: Key used with CTRL/CMD to open the search modal.
metaData: Configure meta-information for the page.
hiddenClients: List of httpsnippet clients to hide from the client's menu, by default hides Unirest, pass [] to show all clients.
onSpecUpdate: Listen to spec changes with a callback function.

For detailed information on how to use these options, refer to the Configuration Section.

Markdown

You can use Markdown in various places, for example in info.description, in your tag descriptions, in your operation descriptions, in your parameter descriptions and in a lot of other places. We’re using GitHub-flavored Markdown. What’s working here, is probably also working in the API reference:

bullet lists, numbered lists
italic, bold, ~~striked~~ text
accordions
links
tables
images
…

Have a look at our OpenAPI example specification to see more examples.

Note: Not everything is supported in all places. For example, you can use images in most places, but not in parameter descriptions.

Layouts

We support two layouts at the moment, a modern layout (the default) and a Swagger UI inspired classic layout (we jazzed it up a bit though).

Themes

You don’t like the color scheme? We’ve prepared some themes for you:

/* theme?: 'alternate' | 'default' | 'moon' | 'purple' | 'solarized' |
'bluePlanet' | 'saturn' | 'kepler' | 'mars' | 'deepSpace' | 'none' */
<ApiReference :configuration="{ theme: 'moon' }" />

Note

The default theme is … the default theme. If you want to make sure no theme is applied, pass none.

Wow, still nothing that fits your brand? Reach out to marc@scalar.com and we’ll make you a custom theme, just for you.

Advanced: Styling

You can pretty much style everything you see. Here’s an extreme example of what’s possible.

To get started, overwrite our CSS variables. We won’t judge.

:root {
  --scalar-font: 'Comic Sans MS', 'Comic Sans', cursive;
}

Note

By default, we’re using Inter and JetBrains Mono, served by Google Fonts. If you use a different font or just don’t want to use Google Fonts, pass withDefaultFonts: true to the configuration.

You can use all variables available in the base styles as well as overwrite the color theme.

To build your own color themes, overwrite the night mode and day mode variables. Here are some basic variables to get you started:

.light-mode {
  --scalar-color-1: #121212;
  --scalar-color-2: rgba(0, 0, 0, 0.6);
  --scalar-color-3: rgba(0, 0, 0, 0.4);
  --scalar-color-accent: #0a85d1;
  --scalar-background-1: #fff;
  --scalar-background-2: #f6f5f4;
  --scalar-background-3: #f1ede9;
  --scalar-background-accent: #5369d20f;
  --scalar-border-color: rgba(0, 0, 0, 0.08);
}
.dark-mode {
  --scalar-color-1: rgba(255, 255, 255, 0.81);
  --scalar-color-2: rgba(255, 255, 255, 0.443);
  --scalar-color-3: rgba(255, 255, 255, 0.282);
  --scalar-color-accent: #8ab4f8;
  --scalar-background-1: #202020;
  --scalar-background-2: #272727;
  --scalar-background-3: #333333;
  --scalar-background-accent: #8ab4f81f;
}

Or get more advanced by styling our sidebar!

.light-mode .sidebar {
  --scalar-sidebar-background-1: var(--scalar-background-1);
  --scalar-sidebar-item-hover-color: currentColor;
  --scalar-sidebar-item-hover-background: var(--scalar-background-2);
  --scalar-sidebar-item-active-background: var(--scalar-background-2);
  --scalar-sidebar-border-color: var(--scalar-border-color);
  --scalar-sidebar-color-1: var(--scalar-color-1);
  --scalar-sidebar-color-2: var(--scalar-color-2);
  --scalar-sidebar-color-active: var(--scalar-color-2);
  --scalar-sidebar-search-background: var(--scalar-background-2);
  --scalar-sidebar-search-border-color: var(--scalar-border-color);
  --scalar-sidebar-search-color: var(--scalar-color-3);
}
.dark-mode .sidebar {
  --scalar-sidebar-background-1: var(--scalar-background-1);
  --scalar-sidebar-item-hover-color: currentColor;
  --scalar-sidebar-item-hover-background: var(--scalar-background-2);
  --scalar-sidebar-item-active-background: var(--scalar-background-2);
  --scalar-sidebar-border-color: var(--scalar-border-color);
  --scalar-sidebar-color-1: var(--scalar-color-1);
  --scalar-sidebar-color-2: var(--scalar-color-2);
  --scalar-sidebar-color-active: var(--scalar-color-2);
  --scalar-sidebar-search-background: var(--scalar-background-2);
  --scalar-sidebar-search-border-color: var(--scalar-border-color);
  --scalar-sidebar-search-color: var(--scalar-color-3);
}

Theme Prefix Changes

We've migrated our --theme-* CSS variables to --scalar-* to avoid conflicts with other CSS variables in applications consuming the Scalar references or themes. If you're injecting your custom CSS through the customCss configuration option we will automatically migrate your variable prefixes but display a warning in the console.

We recommend updating your theme variables as soon as possible:

--theme-* → --scalar-*
--sidebar-* → --scalar-sidebar-*

For a before and after example of an updated theme see legacyTheme.css and updatedTheme.css in the @scalar/themes package.

Community

We are API nerds. You too? Let’s chat on Discord: https://discord.gg/scalar

Packages

This repository contains all our open source projects, and there’s definitely more to discover.

Package	Description
@scalar/api-client-proxy	API request proxy
@scalar/api-client	API testing client
@scalar/api-reference	beautiful API references
@scalar/cli	CLI to work with OpenAPi files
@scalar/echo-server	a server that replies with the request data
@scalar/express-api-reference	Express plugin
@scalar/fastify-api-reference	Fastify plugin
@scalar/galaxy	OpenAPI example specification
@scalar/hono-api-reference	Hono middleware
@scalar/mock-server	fake data based on an OpenAPI specification files
@scalar/nestjs-api-reference	NestJS middleware
@scalar/nextjs-api-reference	Next.js adapter
@scalar/swagger-editor	editor tailored to write OpenAPI files
@scalar/swagger-parser	parse OpenAPI files

Contributors

_hanspagel	_tmastrom	_marclave	_hwkr	_{cameronrohani}	_amritk
_geoffgscott	_ATREAY	_Mohib834	_mcollina	_mouhannad-sh	_Amorim33
_dunklesToast	_{FotieMConstant}	_Chinlinlee	_soulchild	_sinh117801	_dotfortun
_{SebastianBienert}	_Mason-Little	_ShadiestGoat	_IHIutch	_jonataw	_Fdawgs
_danp	_chrislearn	_sigpwned

Contributions are welcome! Read CONTRIBUTING.

License

The source code in this repository is licensed under MIT.

<!doctype html> <html> <head> <title>Scalar API Reference</title> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> </head> <body>   <script id="api-reference" data-url="https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml" data-proxy-url="https://api.scalar.com/request-proxy"></script>  <script> var configuration = { theme: 'purple', } document.getElementById('api-reference').dataset.configuration = JSON.stringify(configuration) </script> <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script> </body> </html>

import { type ReferenceProps } from './types' const ev = new CustomEvent('scalar:update-references-config', { detail: { configuration: { spec: { url: 'https://cdn.scalar.com/spec/openapi_petstore.json', }, }, } satisfies ReferenceProps, }) document.dispatchEvent(ev)

import { ApiReferenceReact } from '@scalar/api-reference-react' import React from 'react' function App() { return ( <ApiReferenceReact configuration={{ spec: { url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml', }, }} /> ) } export default App

### With Next.js Our Next.js handler makes it easy to render a reference; just add it to an API route handler: ```ts // app/reference/route.ts import { ApiReference } from '@scalar/nextjs-api-reference' const config = { spec: { url: '/openapi.json', }, } export const GET = ApiReference(config)

import { swagger } from '@elysiajs/swagger' import { Elysia } from 'elysia' new Elysia() .use(swagger()) .get('/', () => 'hi') .post('/hello', () => 'world') .listen(8080) // open http://localhost:8080/swagger

import type { ScalarOptions } from '@scalar/docusaurus' plugins: [ [ '@scalar/docusaurus', { label: 'Scalar', route: '/scalar', configuration: { spec: { url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml', }, }, } as ScalarOptions, ], ],

use aide::{ axum::{ routing::{get_with}, ApiRouter, IntoApiResponse, }, openapi::OpenApi, scalar::Scalar, }; ... let router: ApiRouter = ApiRouter::new() .api_route_with( "/", get_with( Scalar::new("/docs/private/api.json") .with_title("Aide Axum") .axum_handler(), |op| op.description("This documentation page."), ), |p| p.security_requirement("ApiKey"), ) ...

.light-mode { --scalar-color-1: #121212; --scalar-color-2: rgba(0, 0, 0, 0.6); --scalar-color-3: rgba(0, 0, 0, 0.4); --scalar-color-accent: #0a85d1; --scalar-background-1: #fff; --scalar-background-2: #f6f5f4; --scalar-background-3: #f1ede9; --scalar-background-accent: #5369d20f; --scalar-border-color: rgba(0, 0, 0, 0.08); } .dark-mode { --scalar-color-1: rgba(255, 255, 255, 0.81); --scalar-color-2: rgba(255, 255, 255, 0.443); --scalar-color-3: rgba(255, 255, 255, 0.282); --scalar-color-accent: #8ab4f8; --scalar-background-1: #202020; --scalar-background-2: #272727; --scalar-background-3: #333333; --scalar-background-accent: #8ab4f81f; }

.light-mode .sidebar { --scalar-sidebar-background-1: var(--scalar-background-1); --scalar-sidebar-item-hover-color: currentColor; --scalar-sidebar-item-hover-background: var(--scalar-background-2); --scalar-sidebar-item-active-background: var(--scalar-background-2); --scalar-sidebar-border-color: var(--scalar-border-color); --scalar-sidebar-color-1: var(--scalar-color-1); --scalar-sidebar-color-2: var(--scalar-color-2); --scalar-sidebar-color-active: var(--scalar-color-2); --scalar-sidebar-search-background: var(--scalar-background-2); --scalar-sidebar-search-border-color: var(--scalar-border-color); --scalar-sidebar-search-color: var(--scalar-color-3); } .dark-mode .sidebar { --scalar-sidebar-background-1: var(--scalar-background-1); --scalar-sidebar-item-hover-color: currentColor; --scalar-sidebar-item-hover-background: var(--scalar-background-2); --scalar-sidebar-item-active-background: var(--scalar-background-2); --scalar-sidebar-border-color: var(--scalar-border-color); --scalar-sidebar-color-1: var(--scalar-color-1); --scalar-sidebar-color-2: var(--scalar-color-2); --scalar-sidebar-color-active: var(--scalar-color-2); --scalar-sidebar-search-background: var(--scalar-background-2); --scalar-sidebar-search-border-color: var(--scalar-border-color); --scalar-sidebar-search-color: var(--scalar-color-3); }

Package

Description

@scalar/api-client-proxy

API request proxy

@scalar/api-client

API testing client

@scalar/api-reference

beautiful API references

@scalar/cli

CLI to work with OpenAPi files

@scalar/echo-server

a server that replies with the request data

@scalar/express-api-reference

Express plugin

@scalar/fastify-api-reference

Fastify plugin

@scalar/galaxy

OpenAPI example specification

@scalar/hono-api-reference

Hono middleware

@scalar/mock-server

fake data based on an OpenAPI specification files

@scalar/nestjs-api-reference

NestJS middleware

@scalar/nextjs-api-reference

Next.js adapter

@scalar/swagger-editor

editor tailored to write OpenAPI files

@scalar/swagger-parser

parse OpenAPI files

Scalar

Scalar API Reference

Features

Table of Contents

Getting Started

From a CDN

Events [beta]

scalar:reload-references

scalar:update-references-config

With Nuxt

With Vue.js

With React

With Fastify

With Platformatic

With Hono

With ElysiaJS

With Express

With NestJS

With Docusaurus

With AdonisJS

With Laravel

With Rust

CLI

Installation

Format

Validate

Preview

Mock server

Share

Hosted API Reference

Configuration

Markdown

Layouts

Themes

Advanced: Styling

Theme Prefix Changes

Community

Packages

Contributors

License

Scalar API Reference

Features

Table of Contents

Getting Started

From a CDN

Events [beta]

scalar:reload-references

scalar:update-references-config

With Nuxt

With Vue.js

With React

With Fastify

With Platformatic

With Hono

With ElysiaJS

With Express

With NestJS

With Docusaurus

With AdonisJS

With Laravel

With Rust

CLI

Installation

Format

Validate

Preview

Mock server

Share

Hosted API Reference

Configuration

Markdown

Layouts

Themes

Advanced: Styling

Theme Prefix Changes

Community

Packages

Contributors

License