Scalar API Reference

Generate interactive API documentations from Swagger files. Try our Demo

Installation

npm install @scalar/api-reference

Usage

<script setup>
import { ApiReference } from '@scalar/api-reference'
</script>

<template>
  <ApiReference />
</template>

You can even mount the component in React.

Configuration

There’s a configuration object that can be used on all platforms. In Vue.js, you use it like this:

isEditable?: boolean

Whether the Swagger editor should be shown.

<ApiReference :configuration="{ isEditable: true }" />

spec.content?: string

Directly pass an OpenAPI/Swagger spec.

<ApiReference :configuration="{ spec: { content: '{ … }' } }" />

spec.url?: string

Pass the URL of a spec file (JSON or Yaml).

<ApiReference :configuration="{ spec: { url: '/swagger.json' } }" />

spec.preparsedContent?: string

You can preprocess specs with @scalar/swagger-parser and directly pass the result.

<ApiReference :configuration="{ spec: { preparsedContent : '{ … }' } } />

proxyUrl?: string

Making requests to other domains is restricted in the browser and requires CORS headers. It’s recommended to use a proxy to send requests to other origins.

<ApiReference :configuration="{ proxy: 'https://proxy.example.com' }" />

ℹ️ You can use @scalar/api-client-proxy to host your own proxy or you can just use ours:

<ApiReference
  :configuration="{ proxy: 'https://api.scalar.com/request-proxy' }" />

showSidebar?: boolean

Whether the sidebar should be shown.

<ApiReference :configuration="{ showSidebar: true} />

customCss?: string

You can pass custom CSS directly to the component. This is helpful for the integrations for Fastify, Express, Hono and others where you it’s easier to add CSS to the configuration.

In Vue or React you’d probably use other ways to add custom CSS.

<script setup>
const customCss = `* { font-family: "Comic Sans MS", cursive, sans-serif; }`
</script>

<template>
  <ApiReference :configuration="{ customCss }" />
</template>

searchHotKey?: string

Key used with CNTRL/CMD to open the search modal (defaults to 'k' e.g. CMD+k)

<ApiReference :configuration="{ searchHotKey: 'l'} />

metaData?: object

You can pass information to the config object to configure meta information out of the box.

<ApiReference :configuration="{
  metaData: {
        title: 'Page title',
        description: 'My page page',
        ogDescription: 'Still about my my page',
        ogTitle: 'Page title',
        ogImage: 'https://example.com/image.png',
        twitterCard: 'summary_large_image',
        //Add more...
      }
  } />

onSpecUpdate?: (spec: string) => void

You can listen to spec changes with onSpecUpdate that runs on spec/swagger content change

<ApiReference :configuration="{
    onSpecUpdate: (value: string) => {
      console.log('Content updated:', value)
    }
  } />