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 on Thu Mar, 14th in Discord
Join us to see upcoming features, discuss the roadmap and chat about APIs with us. 💬
- Getting Started
- 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" />
<style>
body {
margin: 0;
}
</style>
</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>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-referenceAnd 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://petstore.swagger.io/v2/swagger.json',
},
}}
/>
)
}
export default AppOur 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: '/swagger.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 a 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: '/swagger.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/swaggerRead 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: '/swagger.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 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"),
)
...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 ofmodernorclassic(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 CNTRL/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 {
--theme-font: 'Comic Sans MS', 'Comic Sans', cursive;
}
We’re using the default- prefix for our variables to not overwrite your variables. You can use all variables without a prefix.
/* ✅ Good (without `default` prefix) */
--theme-font: 'Comic Sans MS', 'Comic Sans', cursive;
/* ❌ Bad (with `default` prefix) */
--default-theme-font: 'Comic Sans MS', 'Comic Sans', cursive;Overwrite our night mode and day mode variables to build your own themes. Here are some of the basic variables to get you started:
.light-mode {
--theme-color-1: #121212;
--theme-color-2: rgba(0, 0, 0, 0.6);
--theme-color-3: rgba(0, 0, 0, 0.4);
--theme-color-accent: #0a85d1;
--theme-background-1: #fff;
--theme-background-2: #f6f5f4;
--theme-background-3: #f1ede9;
--theme-background-accent: #5369d20f;
--theme-border-color: rgba(0, 0, 0, 0.08);
}
.dark-mode {
--theme-color-1: rgba(255, 255, 255, 0.81);
--theme-color-2: rgba(255, 255, 255, 0.443);
--theme-color-3: rgba(255, 255, 255, 0.282);
--theme-color-accent: #8ab4f8;
--theme-background-1: #202020;
--theme-background-2: #272727;
--theme-background-3: #333333;
--theme-background-accent: #8ab4f81f;
}
Or get more advanced by styling our sidebar!
.light-mode .sidebar {
--sidebar-background-1: var(--theme-background-1);
--sidebar-item-hover-color: currentColor;
--sidebar-item-hover-background: var(--theme-background-2);
--sidebar-item-active-background: var(--theme-background-2);
--sidebar-border-color: var(--theme-border-color);
--sidebar-color-1: var(--theme-color-1);
--sidebar-color-2: var(--theme-color-2);
--sidebar-color-active: var(--theme-color-2);
--sidebar-search-background: var(--theme-background-2);
--sidebar-search-border-color: var(--theme-border-color);
--sidebar-search-color: var(--theme-color-3);
}
.dark-mode .sidebar {
--sidebar-background-1: var(--theme-background-1);
--sidebar-item-hover-color: currentColor;
--sidebar-item-hover-background: var(--theme-background-2);
--sidebar-item-active-background: var(--theme-background-2);
--sidebar-border-color: var(--theme-border-color);
--sidebar-color-1: var(--theme-color-1);
--sidebar-color-2: var(--theme-color-2);
--sidebar-color-active: var(--theme-color-2);
--sidebar-search-background: var(--theme-background-2);
--sidebar-search-border-color: var(--theme-border-color);
--sidebar-search-color: var(--theme-color-3);
}
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/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.