@scalar/nextjs-api-reference

Scalar Next.js API Reference Handler

This plugin provides an easy way to render a beautiful API reference based on an OpenAPI/Swagger file with Next.js.

Installation

npm install @scalar/nextjs-api-reference

Usage

If you have a OpenAPI/Swagger file already, you can pass a URL to the plugin in an API Route:

// app/reference/route.ts
import { ApiReference } from '@scalar/nextjs-api-reference'

const config = {
  spec: {
    url: '/openapi.json',
  },
}

export const GET = ApiReference(config)

Or, if you just have a static OpenAPI spec, you can directly pass it as well:

const config = {
  spec: {
    content: '...',
  },
}

We wrote a detailed integration guide for Next.js.

The Next.js handler takes our universal configuration object, read more about configuration in the core package README.

Themes

By default, we’re using a custom Next.js theme and it’s beautiful. But you can choose one of our other themes, too:

const config = {
  theme: 'purple',
}

Pages router

If you are using the pages router, you can import the React component

npm install @scalar/api-reference-react

import { ApiReferenceReact } from '@scalar/api-reference-react'
import '@scalar/api-reference-react/style.css'

export default function References() {
  return (
    <ApiReferenceReact
      configuration={{
        spec: {
          url: 'https://cdn.jsdelivr.net/npm/@scalar/galaxy/dist/latest.json',
        },
      }}
    />
  )
}

Specific CDN version

By default, this integration will use the latest version of the @scalar/api-reference.

You can also pin the CDN to a specific version by specifying it in the CDN string like https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.25.28

You can find all available CDN versions here

// app/reference/route.ts
import { ApiReference } from '@scalar/nextjs-api-reference'

const config = {
  spec: {
    url: '/openapi.json',
  },
  cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference@latest',
}

export const GET = ApiReference(config)