Scalar API

Docus Plus includes a Scalar API Explorer that can be configured with environment variables or the layer's openApi.configurations option. An environment-based OpenAPI source enables Scalar, loads the document, and creates searchable API content. You do not need to write a Markdown page for every endpoint.

Enable integration

Add both variables to the environment profile used for the build:

OPENAPI_SOURCE_TYPE=remote
OPENAPI_SOURCE_LOCATION=https://api.example.com/openapi.json

The source type is either remote or local:

For a local specification, put the file below public/ and use its public path:

OPENAPI_SOURCE_TYPE=local
OPENAPI_SOURCE_LOCATION=openapi/production.json

The file is then available to the browser at /openapi/production.json. The local file must stay inside public/; paths that escape that directory are rejected.

Both variables are required for the environment-based setup. If either is missing, the layer leaves the environment-based API reference disabled. You can still enable Scalar with the config- based setup below.

Multiple references

Use the layer's openApi.configurations array when a site publishes more than one OpenAPI document. Set a pathRouting.basePath segment for each document so every reference has a stable URL:

export default defineNuxtConfig({
  openApi: {
    configurations: [
      {
        title: "Current API",
        badge: { label: "latest", color: "success" },
        url: "https://api.example.com/openapi.json",
        pathRouting: {
          basePath: "/current"
        },
        indexed: true
      },
      {
        title: "API v1.0.0",
        slug: "1.0.0",
        url: "https://api.example.com/v1.0.0/openapi.json",
        pathRouting: {
          basePath: "/1.0.0"
        },
        // Add an optional badge to the dropdown menu
        badge: {
          label: "deprecated",
          color: "neutral",
          variant: "soft",
          size: "xs"
        }
      }
    ]
  }
});

Each configuration can use url or inline content. The base path is appended to /api-reference, so /current is published at /api-reference/current. Scalar also supports multiple sources in a single configuration:

The optional badge uses Nuxt UI BadgeProps and renders as a trailing badge in the API Explorer dropdown. Use it for labels such as latest, deprecated, or new.

export default defineNuxtConfig({
  openApi: {
    configurations: [
      {
        title: "Combined API",
        sources: [
          { url: "https://api.example.com/core/openapi.json", title: "Core" },
          { url: "https://api.example.com/admin/openapi.json", title: "Admin" }
        ],
        pathRouting: {
          basePath: "/combined"
        },
        excludeFromSearch: true
      }
    ]
  }
});

Valid layer OpenAPI configurations enable the integration even when OPENAPI_SOURCE_TYPE and OPENAPI_SOURCE_LOCATION are not set. The API Explorer header button shows a version dropdown when multiple configurations are present. The first configuration is the default unless another one sets default: true.

Use indexed: true on the configuration that should populate generated API content and API search. If no configuration is indexed, the first configuration is used. This keeps older API versions out of the virtual API collection. Set excludeFromSearch: true when a configuration should remain available in Scalar but should not appear in the API Reference search links.

API Explorer

When enabled, the interactive Scalar Explorer is available at:

/api-reference

The layer adds an API Explorer button to the header and an API Reference entry to global search. Scalar is configured with the selected document and uses the same application color mode. The starter's YAML API reference is enabled by its configured Scalar profile.

Consumers can extend the Scalar configuration from nuxt.config.ts when they need an option that is not covered by the shared defaults:

export default defineNuxtConfig({
  scalar: {
    showSidebar: true,
    hideModels: false
  }
});

For a single environment-based document, the integration keeps the API Explorer at /api-reference and supplies the configured OpenAPI URL. With openApi.configurations, each pathRouting.basePath becomes an Explorer route. Use Scalar's Nuxt documentation for additional Scalar-specific options.

Parsing

The OpenAPI document is fetched or read while Nuxt Content prepares its collections. The layer then:

1. Validates the document with Scalar's OpenAPI parser.
2. Normalizes the validated specification so supported OpenAPI versions have a consistent shape.
3. Reads the document information and servers.
4. Creates virtual content entries for the API introduction, tags, operations, and schemas.
5. Extracts useful endpoint and model text for full-text search.
6. Generates a Scalar URL for each entry so search results open the matching Explorer view.

These entries exist in the Nuxt Content database and are kept in memory during generation. They do not create source Markdown files in the consuming repository. The generated content powers API search and the layer's API-aware assistant context in addition to the interactive Scalar page.

The parser also follows local $ref references when collecting operation and schema text. This means parameters, request bodies, responses, and nested model properties can be found through search even when the specification uses reusable components.

Requirements

Remote documents must use HTTPS and must be reachable during the Nuxt build. Local documents must be below public/. The specification must pass validation, and external $ref files are not resolved automatically. Bundle external references into one document before building:

OpenAPI document
├── info, servers
├── paths
│   └── operations, parameters, request/response schemas
└── components
    └── schemas and local #/ references

If parsing fails, the build reports the source URL or path and the validation errors. Fix the specification or the selected profile before deploying; an incomplete API reference should not be silently published.

Environments

Use different profiles when preview and production expose different API contracts:

MODE=preview
OPENAPI_SOURCE_TYPE=remote
OPENAPI_SOURCE_LOCATION=https://preview-api.example.com/openapi.json

MODE=production
OPENAPI_SOURCE_TYPE=remote
OPENAPI_SOURCE_LOCATION=https://api.example.com/openapi.json

The profile selected at build time determines both the document loaded by the parser and the URL used by Scalar in the generated application. Keep the source URL in the profile rather than hard-coding environment-specific values in shared layer code.