Generate interactive API documentation from OpenAPI/Swagger files. Try our Demo
- 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. 💬
<!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://proxy.scalar.com"></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://proxy.scalar.com">
{ … }
</script>
We have recently added two events to the standalone CDN build only.
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'))
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.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
},
},
} satisfies ReferenceProps,
})
document.dispatchEvent(ev)
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.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
},
},
})
Read more: @scalar/nuxt
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 and style to your app:
<script setup lang="ts">
import { ApiReference } from '@scalar/api-reference'
import '@scalar/api-reference/style.css'
</script>
<template>
<ApiReference />
</template>
You can pass props to customize the API reference.
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 '@scalar/api-reference-react/style.css'
import React from 'react'
function App() {
return (
<ApiReferenceReact
configuration={{
spec: {
url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.yaml',
},
}}
/>
)
}
export default App
Our Next.js handler makes it easy to render a reference; just add it to an API route handler:
// app/reference/route.ts
import { ApiReference } from '@scalar/nextjs-api-reference'
const config = {
spec: {
url: '/openapi.json',
},
}
export const GET = ApiReference(config)
Read more: @scalar/nextjs-api-reference
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
Good news: If you’re using a recent version of Platformatic, the Scalar API reference is installed and configured automatically.
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',
},
}),
)
Read more: @scalar/hono-api-reference
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
Read more about @elysiajs/swagger
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,
},
}),
)
Read more: @scalar/express-api-reference
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',
},
}),
)
Read more: @scalar/nestjs-api-reference
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
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.
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.
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"),
)
...
go-scalar-api-reference
by @MarceloPetrucio offers a convenient way to generate
API references in Go:
https://github.com/MarceloPetrucio/go-scalar-api-reference/
- Write your API documentation and publish your API references (free)
- Get SSL and a super cool *.apidocumentation.com subdomain (free)
- Collaborate with your whole team (paid)
- Use any domain (paid)
Ready? Create an account on scalar.com.
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).
Here are a few use cases:
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
Quickly bring your OpenAPI file (JSON or YAML) into shape:
scalar format openapi.json --output openapi.yaml
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 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 serve openapi.json --watch
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? The following command will upload the given specification to our sandbox:
scalar share openapi.json
Read more about the CLI here.
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,
strikedtext - 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.
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 ofmodern
orclassic
(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 ofhttpsnippet
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.
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).
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 [email protected] and we’ll make you a custom theme, just for you.
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.
<style>
:root {
--scalar-font: 'Comic Sans MS', 'Comic Sans', cursive;
}
</style>
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:
<style>
.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;
}
</style>
Or get more advanced by styling our sidebar!
<style>
.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);
}
</style>
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.
We are API nerds. You too? Let’s chat on Discord: https://discord.gg/scalar
This repository contains all our open source projects, and there’s definitely more to discover.
Package | Description |
---|---|
@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 |
Contributions are welcome! Read CONTRIBUTING
.
The source code in this repository is licensed under MIT.