/scalar

Beautiful API references from Swagger/OpenAPI files ✨

Primary LanguageVueMIT LicenseMIT

Scalar API Reference

CI Release Contributors GitHub License Discord

Generate interactive API documentations from Swagger files. Try our Demo

Screenshot of an API Reference

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

Table of Contents

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

Read more: @scalar/hono-api-reference

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

Using our amazing service

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.

Themes

You don’t like the color scheme? We’ve prepared some themes for you:

/* theme?: 'alternate' | 'default' | 'moon' | 'purple' | 'solarized' */
<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:

basic-scalar-variables

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

scalar-sidebar-variables

.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 the open source API testing client
@scalar/api-client-proxy an api request proxy based on express
@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/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

ATREAY
ATREAY
hanspagel
hanspagel
marclave
marclave
hwkr
hwkr
cameronrohani
cameronrohani
amritk
amritk
geoffgscott
geoffgscott
Mohib834
Mohib834
tmastrom
tmastrom
chrislearn
chrislearn
danp
danp
jonataw
jonataw
IHIutch
IHIutch
Mason-Little
Mason-Little
FotieMConstant
FotieMConstant

Contributions are welcome! Read CONTRIBUTING.

License

The source code in this repository is licensed under MIT.