Extraction

Extraction turns your compiled Nest app into openapi/<api id>.json, the file the reference renders. It boots your app in Nest's preview mode, so it never connects to a database, cache or queue. This page covers what happens, every option, and the errors you may meet.

What extraction doesCopy Anchor Link

orbitdocs extract runs this for each API with a source.nest. orbitdocs dev and orbitdocs build run it for you.

› travel: nest build
› travel: extracting from dist/app.module.js (preview mode, no providers started)
✓ travel: 12 operations → /work/orbit-travel/docs/openapi/travel.json

Source optionsCopy Anchor Link

All options live under apis[].source.nest in orbitdocs.config.ts.

module and exportCopy Anchor Link

module is the compiled file, not your TypeScript source. Extraction reads compiled output so it sees the Swagger CLI plugin's metadata.

source: { nest: { module: 'dist/app.module.js', export: 'AppModule' } },

build and rootCopy Anchor Link

build runs in root before every extraction. Leave it out when something else compiles the app, for example in CI after npm run build:

source: { nest: { module: 'dist/app.module.js', build: 'nest build' } },

root defaults to .., the parent of the docs app. In a monorepo, point it at the app:

// Nest monorepo: nest build api → dist/apps/api/main.js
source: {
  nest: {
    root: '..',
    module: 'dist/apps/api/app.module.js',
    build: 'nest build api',
  },
},

@orbitdocs/nestjs must be installed in root, because the extractor runs from there.

globalPrefix and versioningCopy Anchor Link

These mirror the two calls in main.ts that change paths. orbitdocs init copies them for you.

app.setGlobalPrefix('api');
app.enableVersioning({ type: VersioningType.URI, prefix: 'v', defaultVersion: '1' });

source: {
  nest: {
    module: 'dist/app.module.js',
    globalPrefix: 'api',
    versioning: { type: 'uri', prefix: 'v', defaultVersion: '1' },
  },
},

Paths then read /api/v1/bookings. Only URI versioning is supported here; use configure for anything else.

configureCopy Anchor Link

For anything else in main.ts that changes routes, export a hook and point configure at its compiled file:

import type { INestApplication } from '@nestjs/common';

/** Called by OrbitDocs during extraction, before the document is built. */
export function configure(app: INestApplication) {
  app.setGlobalPrefix('api', { exclude: ['health'] });
}

source: { nest: { module: 'dist/app.module.js', configure: 'dist/docs.configure.js#configure' } },

The hook runs after globalPrefix and versioning. Don't set the same thing in both places. You can call the hook from main.ts too, so both share one source of truth.

Environment variables during extractionCopy Anchor Link

Preview mode skips providers, but code that runs while your modules load still runs. For example, ConfigModule.forRoot({ validationSchema }) validates the environment when app.module.js loads. Give it placeholder values:

source: {
  nest: {
    module: 'dist/app.module.js',
    env: {
      DATABASE_URL: 'postgres://placeholder/db',
      STRIPE_SECRET_KEY: 'sk_test_placeholder',
    },
  },
},

Values only fill variables that are not set. A real value in the shell or CI always wins. Never put real secrets here; this file is committed.

When many variables are required, skip the validation during extraction instead. OrbitDocs sets ORBITDOCS_EXTRACT=1 while it loads your module, so your config can check it:

ConfigModule.forRoot({
  // Extraction starts no provider, so it needs no real config.
  validate: (config) => (process.env.ORBITDOCS_EXTRACT === '1' ? config : schema.parse(config)),
}),

Your app never sets ORBITDOCS_EXTRACT when it really starts, so validation stays on there.

API options used by extractionCopy Anchor Link

These live on the API itself, next to source:

Extraction ignores the DocumentBuilder in your main.ts. Set the title, servers and security schemes here instead. See Authentication.

Operation idsCopy Anchor Link

Each kept operation gets a readable id, made from its title: Create a booking becomes create-a-booking. The id is used in URLs, op: links and file names under reference/. Nest's own id, such as BookingsController_create, is kept as x-orbitdocs-handler.

Standard errorsCopy Anchor Link

With standardErrors: true (the default), extraction adds the errors each operation returns by construction:

• 400 when the operation takes parameters or a body.
• 401 and 403 when the operation is secured.
• 404 when the path has a parameter.
• 500 always.

Each 4xx and 5xx response without a body gets the shared ErrorResponse schema, Nest's default exception body:

{ "statusCode": 404, "message": "Not Found" }

Your own descriptions from @DocsErrors or @ApiResponse win. Set standardErrors: false on the API to add nothing.

Run extraction yourselfCopy Anchor Link

npx orbitdocs extract               # every API
npx orbitdocs extract --api travel  # one API
npx orbitdocs extract --skip-build  # don't run the build command

Run these in the docs app. orbitdocs extract exits with code 1 when an API with completeness: 'error' has gaps.

In orbitdocs devCopy Anchor Link

orbitdocs dev extracts once, then watches for changes:

• With build set, it watches the Nest source folder and runs build, then extraction, after each change. The folder is sourceRoot from nest-cli.json in root (default src); without that folder it watches root, ignoring node_modules, the build output and the docs app.
• Without build, it watches the folder of the compiled module. Run nest start --watch in another terminal.

Changes are grouped for 600 ms. If extraction fails at startup, the docs still start; fix the API and save to retry.

Use the document in your own codeCopy Anchor Link

@orbitdocs/nestjs also exports the filter as a function, for example to save the public spec from a script:

import { writeFileSync } from 'node:fs';

import { NestFactory } from '@nestjs/core';
import { DocumentBuilder } from '@nestjs/swagger';
import { createOrbitDocument } from '@orbitdocs/nestjs';

import { AppModule } from '../app.module';

async function main() {
  const app = await NestFactory.create(AppModule, { preview: true, abortOnError: false });
  const doc = createOrbitDocument(app, {
    base: new DocumentBuilder().setTitle('Orbit Travel API').setVersion('1.0.0').build(),
    mode: 'opt-in',
    standardErrors: { extra: ['429'] },
  });
  writeFileSync('openapi.json', JSON.stringify(doc, null, 2));
  await app.close();
}

void main();

createFullDocument(app, base?) returns the unfiltered document Nest would serve.

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link