Generate interactive API documentations from Swagger files. Try our Demo
- Uses Swagger/OpenAPI spec files
- Request examples for a ton of languages + frameworks
- Has an integrated API client
- Edit your Swagger files with a live preview
- Doesn’t look like it’s 2011
Scalar Townhall every 2nd Thursday in Discord
Join us to see upcoming features, discuss the roadmap and chat about APIs with us. 💬
- Getting Started
- CLI
- Hosted API Reference
- Configuration
- Layouts
- Themes
- Advanced: Styling
- Community
- Packages
- Contributors
- License
<!doctype html>
<html>
<head>
<title>API Reference</title>
<meta charset="utf-8" />
<meta
name="viewport"
content="width=device-width, initial-scale=1" />
</head>
<body>
<!-- Add your own OpenAPI/Swagger spec file URL here: -->
<!-- Note: this includes our proxy, you can remove the following line if you do not need it -->
<!-- data-proxy-url="https://api.scalar.com/request-proxy" -->
<script
id="api-reference"
data-url="https://petstore3.swagger.io/api/v3/openapi.json"
data-proxy-url="https://api.scalar.com/request-proxy"></script>
<!-- You can also set a full configuration object like this (easier for nested objects): -->
<script>
var configuration = {
theme: 'purple',
}
var apiReference = document.getElementById('api-reference')
apiReference.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 spec:
<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>
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',
},
},
})
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. Just install them:
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.
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 (untested on SSR/SSG) wrapper in react.
import { ApiReferenceReact } from '@scalar/api-reference-react'
import React from 'react'
function App() {
return (
<ApiReferenceReact
configuration={{
spec: {
url: 'https://petstore3.swagger.io/api/v3/openapi.json',
},
}}
/>
)
}
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://petstore3.swagger.io/api/v3/openapi.json',
},
},
} 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. Just 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. Just 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"),
)
...
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’s 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 reference 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? It’s as easy as this:
scalar share openapi.json
Read more about the CLI here.
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.
To customize the behavior of the API Reference, you can use the following configuration options:
isEditable
: Whether the Swagger editor should be shown.spec.content
: Directly pass an OpenAPI/Swagger spec.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 them 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 clients 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' }" />
ℹ️ The default
theme is … the default theme. If you want to make sure no theme is applied, pass none
.
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);
}
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/8HeZcRGPFS
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/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.