configuration.md

Configuration

There’s a universal configuration object that can be used on all platforms.

isEditable?: boolean

Whether the Swagger editor should be shown.

{
  isEditable: true
}

spec.content?: string

Directly pass an OpenAPI/Swagger spec.

{
  spec: {
    content: '{ … }'
  }
}

spec.url?: string

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

{
  spec: {
    url: '/openapi.json'
  }
}

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.

{
  proxy: 'https://proxy.example.com'
}

You can use our hosted proxy:

{
  proxy: 'https://proxy.scalar.com'
}

If you like to run your own, check out our example proxy written in Go.

showSidebar?: boolean

Whether the sidebar should be shown.

{
  showSidebar: true
}

hideModels?: boolean

Whether models (components.schemas or definitions) should be shown in the sidebar, search and content.

@default false

{
  hideModels: true
}

hideDownloadButton?: boolean

Whether to show the "Download OpenAPI Specification" button

@default false

{
  hideDownloadButton: true
}

darkMode?: boolean

Whether dark mode is on or off initially (light mode)

{
  darkMode: true
}

forceDarkModeState?: 'dark' | 'light'

forceDarkModeState makes it always this state no matter what

{
  forceDarkModeState: 'dark'
}

hideDarkModeToggle?: boolean

Whether to show the dark mode toggle

{
  hideDarkModeToggle: 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.

{
  customCss: `* { font-family: "Comic Sans MS", cursive, sans-serif; }`
}

searchHotKey?: string

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

{
  searchHotKey: 'l'
}

servers?: Server[]

List of servers to override the openapi spec servers

@default undefined @example [{ url: 'https://api.scalar.com', description: 'Production server' }]

{
  servers: [
    {
      url: 'https://api.scalar.com',
      description: 'Production server',
    },
  ]
}

metaData?: object

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

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

defaultHttpClient?: HttpClientState

By default, we’re using Shell/curl as the default HTTP client. Or, if that’s disabled (through hiddenClients), we’re just using the first available HTTP client.

You can explicitly set the default HTTP client, though:

{
  defaultHttpClient: {
    targetKey: 'node',
    clientKey: 'undici',
  }
}

hiddenClients?: array | true

You can pass an array of httpsnippet clients to hide from the clients menu.

{
  hiddenClients: ['fetch']
}

By default hides Unirest, pass [] to show all clients:

{
  hiddenClients: []
}

Or true to hide all clients:

{
  hiddenClients: true
}

onSpecUpdate?: (spec: string) => void

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

{
  onSpecUpdate: (value: string) => {
    console.log('Content updated:', value)
  }
}

authentication?: Partial

To make authentication easier you can prefill the credentials for your users:

{
  authentication: {
    // The OpenAPI file has keys for all security schemes:
    // Which one should be used by default?
    preferredSecurityScheme: 'my_custom_security_scheme',
    // The `my_custom_security_scheme` security scheme is of type `apiKey`, so prefill the token:
    apiKey: {
      token: 'super-secret-token',
    },
  },
}

For OpenAuth2 it’s more looking like this:

{
  authentication: {
    // The OpenAPI file has keys for all security schemes
    // Which one should be used by default?
    preferredSecurityScheme: 'oauth2',
    // The `oauth2` security scheme is of type `oAuth2`, so prefill the client id and the scopes:
    oAuth2: {
    clientId: 'foobar123',
    // optional:
    scopes: ['read:planets', 'write:planets'],
    },
  },
}

withDefaultFonts?: boolean

By default we’re using Inter and JetBrains Mono, served by Google Fonts. If you use a different font or just don’t want to use Google Fonts, pass withDefaultFonts: false to the configuration.

{
  withDefaultFonts: false
}

defaultOpenAllTags?: boolean

By default we only open the relevant tag based on the url, however if you want all the tags open by default then set this configuration option :)

{
  defaultOpenAllTags: true
}

tagsSorter?: 'alpha' | (a: Tag, b: Tag) => number

Sort tags alphanumerically ('alpha'):

{
  tagsSorter: 'alpha'
}

Or specify a custom function to sort the tags.

Note: Most of our integrations pass the configuration as JSON and you can’t use custom sort functions there. It will work in Vue, Nuxt, React, Next and all integrations that don’t need to pass the configuration as a JSON string.

{
  /** @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort */
  tagsSorter: (a, b) => {
    if (a.name === 'Super Important Tag') return -1
    return 1
  }
}

Learn more about Array sort functions: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort

theme?: string

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

Can be one of: alternate, default, moon, purple, solarized, bluePlanet, saturn, kepler, mars, deepSpace, none

{
  theme: 'default'
}