Scalar Module

Scalar Module

The Scalar module serves your OpenAPI schema as JSON and provides beautiful interactive API documentation powered by Scalar .

Basic Setup

Create a route at src/routes/api-docs/[slug]/+server.ts:

import ScalarModule from "sveltekit-auto-openapi/scalar-module";

export const { GET, _config } = ScalarModule({
  openApiOpts: {
    openapi: "3.0.0",
    info: {
      title: "My App API",
      version: "1.0.0",
    },
  },
});
ts

This creates two endpoints:

  • /api-docs/openapi.json - OpenAPI schema
  • /api-docs/scalar - Interactive documentation UI

Configuration Options

Basic OpenAPI Configuration

Configure your OpenAPI document metadata:

ScalarModule({
  openApiOpts: {
    openapi: "3.0.0",
    info: {
      title: "My App API",
      version: "1.0.0",
      description: "API documentation for My App",
      contact: {
        name: "API Support",
        email: "support@example.com",
      },
    },
    servers: [
      {
        url: "https://api.example.com",
        description: "Production",
      },
      {
        url: "http://localhost:5173",
        description: "Development",
      },
    ],
  },
});
ts

Schema Endpoint Options

Control the OpenAPI JSON endpoint:

ScalarModule({
  disableOpenApi: false,              // Disable OpenAPI endpoint
  openApiPath: "openapi.json",        // Custom path (default: "openapi.json")
  showDetailedDocsSchema: false,      // Include full schema in response
  skipDocsValidation: false,          // Skip runtime schema validation
  openApiOpts: { /* ... */ },
});
ts

Documentation UI Options

Control the Scalar documentation interface:

ScalarModule({
  disableScalar: false,               // Disable Scalar UI
  scalarDocPath: "scalar",            // Custom path (default: "scalar")
  scalarOpts: {
    theme: "purple",                  // Scalar theme
    layout: "modern",                 // Layout style
  },
  openApiOpts: { /* ... */ },
});
ts

Override Paths

Completely override the generated paths:

ScalarModule({
  overridePaths: {
    "/api/custom": {
      get: {
        summary: "Custom endpoint",
        responses: { /* ... */ },
      },
    },
  },
  openApiOpts: { /* ... */ },
});
ts

Endpoints

OpenAPI JSON Schema

URL: /api-docs/openapi.json

Returns the complete OpenAPI schema in JSON format.

Example response:

{
  "openapi": "3.0.0",
  "info": { "title": "My App API", "version": "1.0.0" },
  "paths": {
    "/api/users": { /* ... */ }
  }
}
js

Scalar Documentation UI

URL: /api-docs/scalar

Serves an interactive API documentation interface where you can:

  • Browse all endpoints
  • View request/response schemas
  • Try out API calls directly
  • See examples and descriptions

Customization

Custom Branding

Customize the documentation appearance:

ScalarModule({
  scalarOpts: {
    theme: "purple",
    customCss: `
      .scalar-app {
        --scalar-color-1: #ff9e64;
      }
    `,
  },
  openApiOpts: { /* ... */ },
});
ts

Custom Servers

Define multiple API servers:

ScalarModule({
  openApiOpts: {
    openapi: "3.0.0",
    info: { /* ... */ },
    servers: [
      { url: "https://api.example.com", description: "Production" },
      { url: "https://staging-api.example.com", description: "Staging" },
      { url: "http://localhost:5173", description: "Local" },
    ],
  },
});
ts

Security Schemes

Add authentication documentation:

ScalarModule({
  openApiOpts: {
    openapi: "3.0.0",
    info: { /* ... */ },
    components: {
      securitySchemes: {
        bearerAuth: {
          type: "http",
          scheme: "bearer",
          bearerFormat: "JWT",
        },
        apiKey: {
          type: "apiKey",
          in: "header",
          name: "X-API-Key",
        },
      },
    },
    security: [{ bearerAuth: [] }],
  },
});
ts

Route Structure

The [slug] parameter distinguishes between endpoints:

  • slug === "openapi.json" → Serves OpenAPI schema
  • slug === "scalar" → Serves Scalar UI
  • Other values → 404

Disabling Endpoints

Disable OpenAPI JSON

ScalarModule({
  disableOpenApi: true,
  openApiOpts: { /* ... */ },
});
ts

Now only /api-docs/scalar works.

Disable Scalar UI

ScalarModule({
  disableScalar: true,
  openApiOpts: { /* ... */ },
});
ts

Now only /api-docs/openapi.json works.

Custom Paths

ScalarModule({
  openApiPath: "schema.json",      // /api-docs/schema.json
  scalarDocPath: "docs",           // /api-docs/docs
  openApiOpts: { /* ... */ },
});
ts

Next Steps

Last update at: Invalid Date