NestJS decorators and functions

@orbitdocs/nestjs adds a few optional decorators on top of @nestjs/swagger, plus functions to build the document and serve the docs. The decorators only write OpenAPI extensions or Swagger responses. They never change routing, guards or behavior.

import { DocsContent, DocsErrors, DocsExtension, DocsHidden, DocsOperation, DocsSamples, mountOrbitDocs } from '@orbitdocs/nestjs';

Every Swagger decorator (@ApiOperation, @ApiTags, @ApiResponse, @ApiProperty, @ApiBearerAuth, @ApiExcludeEndpoint, …) and the Swagger CLI plugin drive the docs as usual. With routes: 'all' you need none of the decorators below.

DecoratorsCopy Anchor Link

@DocsOperationCopy Anchor Link

function DocsOperation(options?: DocsOperationOptions)

Puts a route in the public reference. With routes: 'opt-in' (the default) only routes with this decorator appear.

@Post()
@DocsOperation({ group: 'Bookings', title: 'Create a booking', order: 1 })
create(@Body() dto: CreateBookingDto) {}

When title is set and Swagger's summary differs, the summary becomes the description (unless one is given).

@DocsHiddenCopy Anchor Link

function DocsHidden()

Keeps a route out of the reference even when it is marked or routes: 'all' is on. Same effect as Swagger's @ApiExcludeEndpoint() for the docs.

@DocsErrorsCopy Anchor Link

function DocsErrors(errors: Partial<Record<number, string>>)

Documents the errors one route returns, and when. Generic codes are added automatically when standardErrors is on: 400 with input, 401 and 403 when secured, 404 with a path parameter, 500. List what this route adds or says more about.

@DocsErrors({ 404: 'No booking with this id.', 409: 'The flight is full.' })

@DocsSamplesCopy Anchor Link

function DocsSamples(samples: CodeSample[])

interface CodeSample {
  lang: string;   // highlighting: typescript, python, go, shell…
  label?: string; // tab label; defaults to lang
  source: string;
}

Hand-written samples, shown before the generated ones. A hand-written sample with the same label as a generated one replaces it.

@DocsExtensionCopy Anchor Link

function DocsExtension(key: `x-${string}`, value: unknown)

Any OpenAPI x- extension on the operation, for plugins or your own tools.

@DocsContentCopy Anchor Link

function DocsContent(markdown: string, position?: ContentPosition)

type ContentPosition = 'before-parameters' | 'after-description' | 'after-responses' | 'aside';

@DocsContent('> [!WARNING]\n> Cancelling within 24 h of departure is not refunded.', 'before-parameters')

For longer content with components, use reference/<api>/<operation>.mdx. See Operation content.

mountOrbitDocsCopy Anchor Link

function mountOrbitDocs(app: INestApplication, options: MountOrbitDocsOptions): void

Serves the static docs build from the Nest app (Express adapter only). Call it in main.ts before app.listen(). Throws when root doesn't exist (OrbitDocs build not found at …) or the adapter isn't Express.

See Inside your Nest app.

Document helpersCopy Anchor Link

For building the document yourself, for example in a test or a custom script:

function createFullDocument(app: INestApplicationContext, base?: Omit<OpenAPIObject, 'paths'>): Document
function createOrbitDocument(app: INestApplicationContext, options?: OrbitDocumentOptions): Document

• createFullDocument returns everything SwaggerModule.createDocument produces (with deepScanRoutes). base defaults to title API, version 1.0.0.
• createOrbitDocument returns the public document: marked routes only, readable operation ids, standard errors and unused schemas pruned.

A schema that is referenced but never defined throws DanglingReferenceError. In NestJS, register it with @ApiExtraModels() or type the property.

extractCopy Anchor Link

function extract(request: ExtractRequest): Promise<ExtractResult>

The function behind orbitdocs extract. It boots a compiled module in preview mode and writes the filtered document. The CLI calls it through @orbitdocs/nestjs/extract-cli; you rarely need it directly. See Extraction.

Exported typesCopy Anchor Link

DocsOperationOptions, CodeSample, MountOrbitDocsOptions, OrbitDocumentOptions, ExtractRequest, ExtractResult, and from @orbitdocs/openapi: ORBIT_EXTENSION ('x-orbitdocs'), OrbitMarker, Stability.