API Reference for Astro Starlight

This is a Starlight plugin that renders a beautiful API reference based on an OpenAPI/Swagger document, right inside your Starlight docs.

Unlike embedding the @scalar/astro component on a page yourself, the plugin injects the route and adds the sidebar entry for you.

Installation

npm install @scalar/starlight

Usage

Add the plugin to your Starlight configuration and point it at an OpenAPI document:

// astro.config.mjs
import { defineConfig } from 'astro/config'
import starlight from '@astrojs/starlight'
import { scalarStarlight } from '@scalar/starlight'

export default defineConfig({
  integrations: [
    starlight({
      title: 'My Docs',
      plugins: [
        scalarStarlight({
          // How to configure Scalar:
          // https://scalar.com/products/api-references/configuration
          configuration: {
            url: '/openapi.json',
          },
        }),
      ],
    }),
  ],
})

By default the API reference is served from /api-reference and shows up as an API Reference entry in the Starlight sidebar.

The sidebar entry is only added when you define a sidebar in your Starlight config. If you leave sidebar unset, Starlight auto-generates it from your docs — the plugin then does not add the entry (that would replace the auto-generated sidebar and hide your other pages) and logs a note instead. Add the link yourself, e.g. sidebar: [{ label: 'API Reference', link: '/api-reference' }].

The plugin takes our universal configuration object, read more about configuration.

Options

Option	Default	Description
`configuration`	—	Scalar's universal configuration object.
`pathname`	`'/api-reference'`	The path the API reference is served from.
`label`	`'API Reference'`	The label of the sidebar entry.
`title`	the `label`	The title of the API reference page.

Custom path and label

scalarStarlight({
  configuration: { url: '/openapi.json' },
  pathname: '/reference',
  label: 'API',
})

Multiple references

Add the plugin more than once, each with its own pathname, to serve several API references from one site:

plugins: [
  scalarStarlight({ pathname: '/reference/payments', label: 'Payments', configuration: { url: '/payments.json' } }),
  scalarStarlight({ pathname: '/reference/billing', label: 'Billing', configuration: { url: '/billing.json' } }),
]

The configuration is serialized into the page as JSON, so function-valued options (a custom fetch, onLoaded, plugins, …) are not carried over. The plugin builds on @scalar/astro's client render mode so the reference keeps working across Starlight's client-side navigation (view transitions).

Spry

SvelteKit

The API company.