API reference

Each API in orbitdocs.config.ts gets a Scalar-style reference at /reference/<api id>. It is one scrolling page with a sidebar, and every operation also has its own URL. Open the demo reference next to this page to follow along.

What's in this sectionCopy Anchor Link

Add an APICopy Anchor Link

import { defineConfig } from '@orbitdocs/next/config';

export default defineConfig({
  site: { title: 'Orbit Travel' },
  apis: [
    {
      id: 'travel',
      title: 'Orbit Travel API',
      source: { nest: { module: 'dist/app.module.js', build: 'nest build' } },
    },
  ],
});

The reference appears at /reference/travel, and an API Reference link appears in the top bar.

One page, a URL per operationCopy Anchor Link

The whole API renders as one page, so readers can scroll and search it in the browser. Every section also has its own pre-rendered URL:

Each URL has its own title, such as Create a booking · Orbit Travel API, and its own meta description. As the reader scrolls, the address bar follows the section in view, so a copied URL always points at what they read. Search engines index every operation.

Pages stay small however big the API is. Each URL ships its own operation fully rendered (about 200 KB of HTML for a 33-operation API), and the other sections load in the background from reference/<api id>/sections/<group>.json, closest to the reader first. Within a second or two the whole API is on the page, so scrolling, the sidebar and Ctrl+F work as on one long page. Without JavaScript, each placeholder links to that operation's own URL.

LayoutCopy Anchor Link

SidebarCopy Anchor Link

The sidebar lists every group and its operations, with a method badge each. A filter box at the top narrows the list as you type. The group of the current operation opens by itself. On small screens the sidebar becomes a menu with the current section's name.

IntroductionCopy Anchor Link

The first section shows:

• The API version (from version or the spec) and the OpenAPI version, as badges.
• The title and a Download OpenAPI Document link.
• The description, in Markdown, followed by your reference/<api id>/index.mdx.
• In the right column: the Server picker, the Authentication card and the Client Libraries language picker.

GroupsCopy Anchor Link

Operations are grouped by tag. In a Nest app, that is the group of @DocsOperation or @ApiTags. Each group shows its heading, its description, your _groups/<group>.mdx file and a list of its operations.

Order:

• Operations without a group come first, without a heading.
• Groups follow the spec's tag order, then the order they first appear.
• Inside a group, operations follow their order, then their order in the spec.

Each operationCopy Anchor Link

The left column documents the operation. The right column shows samples and stays in view while you scroll.

Test Request opens the API client on this operation, with the server and credentials already filled in. With send: false on the API, Test Request is disabled and explains why on hover; the code samples and Copy stay. See Turn sending off for one API.

FieldsCopy Anchor Link

Every parameter and schema field shows its name, type (such as string · email or Booking[]), and flags: required, read-only, write-only, deprecated. Below that come the description, enum values, default, example, minimum, maximum and pattern. Required fields come first. Nested objects open with Show child attributes.

Request bodies hide read-only fields, and responses hide write-only fields.

ModelsCopy Anchor Link

The last section lists every named object and enum schema, except the shared ErrorResponse. Each one expands to its fields.

More for each APICopy Anchor Link

• Download. The spec is published at /openapi/<api id>.json.
• Copy as Markdown. Each operation copies as Markdown, for an issue or an LLM chat.
• Search. ⌘K or Ctrl+K searches operations by title, method and path, description and parameter names, along with guides.
• llms.txt. /llms.txt lists every operation, and /llms-full.txt includes the whole API as Markdown. See llms.txt.
• Your content. Add notes, tabs and warnings to the API, a group or an operation. See Operation content.

What the reader's browser remembersCopy Anchor Link

The reference stores three choices per API in the reader's browser, under orbitdocs:<api id> in localStorage:

• the selected code sample language;
• the selected server;
• the credentials entered in the Authentication card.

Nothing is sent anywhere except to your API when the reader sends a request.

Next stepsCopy Anchor Link