Express

This middleware provides an easy way to render a beautiful API reference based on an OpenAPI/Swagger file with Express.

Installation Copied

npm install @scalar/express-api-reference

Usage Copied

Set up Express and pass an URL to an OpenAPI/Swagger document to the apiReference middleware:

Wait, but how do we get the OpenAPI document? 🤔 There are multiple ways to generate an OpenAPI file for Express. The most popular way is to use swagger-jsdoc.

import { apiReference } from '@scalar/express-api-reference'

app.use(
  '/reference',
  apiReference({
    // Put your OpenAPI url here:
    url: '/openapi.json',
  }),
)

The Express middleware takes our universal configuration object, read more about configuration in the core package README.

Themes Copied

The middleware comes with a custom theme for Express. You can use one of the other predefined themes (alternate, default, moon, purple, solarized) or overwrite it with none. All themes come with a light and dark color scheme.

import { apiReference } from '@scalar/express-api-reference'

app.use(
  '/reference',
  apiReference({
    theme: 'purple',
    url: '/openapi.json',
  }),
)

Custom CDN Copied

You can use a custom CDN, default is https://cdn.jsdelivr.net/npm/@scalar/api-reference.

import { apiReference } from '@scalar/express-api-reference'

app.use(
  '/reference',
  apiReference({
    cdn: 'https://cdn.jsdelivr.net/npm/@scalar/api-reference',
    url: '/openapi.json',
  }),
)

Usage with Express Zod API Copied

The wonderful express-zod-api package makes it easy to generate an OpenAPI document for your Express API.

To render a beautiful UI using Scalar, you just need to install our integration:

npm install @scalar/express-api-reference

And then hook into Express and pass the apiReference middleware with the OpenAPI document:

import { createConfig } from 'express-zod-api'
import { apiReference } from '@scalar/express-api-reference'

const config = createConfig({
  beforeRouting: ({ app, getLogger }) => {
    const logger = getLogger()
    logger.info('Serving the API reference at https://example.com/docs')

    app.use(
      '/docs',
      apiReference({
        // Pass your generated OpenAPI document
        content: documentation.getSpecAsJson(),
      }),
    )
  },
})

Community Copied

We are API nerds. You too? Let's chat on Discord: https://discord.gg/scalar

License Copied

The source code in this repository is licensed under MIT.