Scalar API Reference

Generate interactive API documentations from Swagger files. Try our Demo

Features

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

From a CDN

<!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://example.com/swagger.json"
      data-proxy-url="https://api.scalar.com/request-proxy"></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>

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. 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.

With React

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

With Fastify

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

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: '/swagger.json',
    },
  }),
)

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,
    },
  }),
)

Read more: @scalar/express-api-reference

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: '/swagger.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:

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 of modern or classic (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.
onSpecUpdate: Listen to spec changes with a callback function.

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

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' | 'none' */
<ApiReference :configuration="{ theme: 'moon' }" />

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

Advanced: Styling

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);
}

Community

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

Other packages

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

Contributors

_hanspagel	_tmastrom	_marclave	_hwkr	_{cameronrohani}	_amritk
_geoffgscott	_ATREAY	_Mohib834	_mouhannad-sh	_chrislearn	_danp
_jonataw	_IHIutch	_Mason-Little	_sinh117801	_Chinlinlee	_{FotieMConstant}

Contributions are welcome! Read CONTRIBUTING.

License

The source code in this repository is licensed under MIT.

Name		Name	Last commit message	Last commit date
Latest commit History 1,215 Commits
.changeset		.changeset
.github		.github
.vscode		.vscode
examples		examples
packages		packages
patches		patches
scripts		scripts
.eslintrc.cjs		.eslintrc.cjs
.gitignore		.gitignore
.npmrc		.npmrc
.nvmrc		.nvmrc
.prettierignore		.prettierignore
.prettierrc		.prettierrc
.syncpackrc		.syncpackrc
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING		CONTRIBUTING
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
RELEASE.md		RELEASE.md
lefthook.yml		lefthook.yml
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.json		tsconfig.json
turbo.json		turbo.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Scalar API Reference

Features

Table of Contents

Getting Started

From a CDN

With Vue.js

With React

With Fastify

With Hono

With Express

With NestJS

Hosted API Reference

Configuration

Layouts

Themes

Advanced: Styling

Community

Other packages

Contributors

License

About

Releases

Packages

Languages

License

feitianbubu/scalar

Folders and files

Latest commit

History

Repository files navigation

Scalar API Reference

Features

Table of Contents

Getting Started

From a CDN

With Vue.js

With React

With Fastify

With Hono

With Express

With NestJS

Hosted API Reference

Configuration

Layouts

Themes

Advanced: Styling

Community

Other packages

Contributors

License

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages