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
- Getting Started
- Hosted API Reference
- Configuration
- Layouts
- Themes
- Advanced: Styling
- Community
- Other packages
- Contributing
- 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-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. You can use veaury to load the <APIReference />
component in React:
import { ApiReference as VueComponent } from '@scalar/api-reference'
import { applyVueInReact } from 'veaury'
const ApiReference = applyVueInReact(VueComponent)
function App() {
return (
<>
<ApiReference configuration={{ isEditable: true }} />
</>
)
}
export default App
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',
})
Read more: @scalar/fastify-api-reference
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
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
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',
// …
];
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).spec.preparsedContent
: Preprocess specs with@scalar/swagger-parser
and directly pass the result.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 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 | an API request proxy based on express |
@scalar/api-client | the open source API testing client |
@scalar/api-reference | generate beautiful API references |
@scalar/echo-server | an express server which replies with the request data |
@scalar/fastify-api-reference | a fastify plugin to render API references |
@scalar/hono-api-reference | a Hono middleware to render API references |
@scalar/nestjs-api-reference | a NestJS middleware to render API references |
@scalar/swagger-editor | an editor tailored to write OpenAPI spec |
@scalar/swagger-parser | parse OpenAPI specs |
@scalar/use-clipboard | tiny Vue wrapper around the clipboard API |
@scalar/use-codemirror | CodeMirror for Vue |
@scalar/use-keyboard-event | keyboard shortcuts for Vue |
@scalar/use-toasts | display toasts in Vue |
@scalar/use-tooltip | tooltips in Vue |
Contributions are welcome! Read CONTRIBUTING
.
The source code in this repository is licensed under MIT.