Decorators

The @Docs* decorators from @orbitdocs/nestjs are thin wrappers around Swagger's ApiExtension and ApiResponse. They only add documentation metadata. They never change routing, guards or behavior.

You need them in one case: with routes: 'opt-in' (the default), @DocsOperation is what puts a route in the docs. With routes: 'all', every decorator here is optional.

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

@DocsOperationCopy Anchor Link

Publishes one route and describes how it reads in the reference.

/**
 * Books seats on a flight for one or more passengers. The booking is
 * confirmed immediately when seats are available.
 */
@Post()
@DocsOperation({ group: 'Bookings', title: 'Create a booking', order: 1 })
create(@Body() dto: CreateBookingDto): BookingDto {
  // ...
}

Every option is optional. @DocsOperation() with no options publishes the route with its Swagger title and tags.

Titles become URLsCopy Anchor Link

The title is turned into the operation's slug: lowercase, words joined by -, text in parentheses dropped, at most eight words. Two operations with the same slug get -2, -3 and so on.

Where the description comes fromCopy Anchor Link

With the Swagger CLI plugin and introspectComments, the JSDoc comment above a method lands in Swagger's summary. When @DocsOperation sets a title, OrbitDocs moves that comment into the description. So a JSDoc comment plus a title is all you need.

In routes: 'all' mode without @DocsOperation, the plugin's rules apply as they are:

• No @ApiOperation: the JSDoc comment becomes the title.
• @ApiOperation({ summary }): the plugin ignores the JSDoc comment. Put the text in @ApiOperation({ description }).

To keep JSDoc comments as descriptions in all mode, set the plugin's controllerKeyOfComment to description and give each route a summary:

{
  "name": "@nestjs/swagger",
  "options": { "introspectComments": true, "controllerKeyOfComment": "description" }
}

Mark a whole controllerCopy Anchor Link

Put @DocsOperation on the class to publish every route in it:

@DocsOperation({ group: 'Flights' })
@Controller('flights')
export class FlightsController {
  @Get()
  @ApiOperation({ summary: 'Search flights' })
  search() {}

  @Get(':id')
  @ApiOperation({ summary: 'Get a flight' })
  get() {}
}

@DocsHiddenCopy Anchor Link

Keeps a route out of the docs. Use it on routes in a marked controller, or on any route with routes: 'all':

@Get('legacy')
@DocsHidden()
legacy() {}

@ApiExcludeEndpoint() from @nestjs/swagger has the same effect for the docs and also hides the route from Swagger UI.

@DocsErrorsCopy Anchor Link

Documents the errors one route returns, and when:

@Post()
@DocsOperation({ group: 'Bookings', title: 'Create a booking' })
@DocsErrors({
  404: 'No flight with this id.',
  409: 'Not enough seats left in this cabin.',
})
create(@Body() dto: CreateBookingDto) {}

The argument maps a status code to a description. Each entry becomes an @ApiResponse({ status, description }).

You don't list the generic codes. OrbitDocs adds them to every operation:

A description you give wins over the generic one. Every 4xx and 5xx response without its own body gets the shared ErrorResponse schema (Nest's { statusCode, message, error }) and an example. Set standardErrors: false on the API to turn all of this off.

@DocsSamplesCopy Anchor Link

Hand-written code samples, shown before the generated ones:

@DocsSamples([
  {
    lang: 'typescript',
    label: 'TypeScript SDK',
    source: "const booking = await orbit.bookings.create({ flightId: 'flt_2031_proxima', cabin: 'economy' });",
  },
])

orbitdocs sdk can generate SDK samples for every operation instead. See Code samples.

@DocsContentCopy Anchor Link

Adds Markdown inside the operation's section:

@Post(':id/cancel')
@DocsOperation({ group: 'Bookings', title: 'Cancel a booking' })
@DocsContent('> [!WARNING]\n> Cancelling less than 24 hours before departure is not refunded.')
cancel(@Param('id') id: string) {}

GitHub alerts (NOTE, TIP, IMPORTANT, WARNING, CAUTION) render as callouts. The second argument sets where the content goes:

Use one @DocsContent per method; only the one closest to the method is kept. For longer content with components, write reference/<api id>/<operation>.mdx instead. See Operation content.

@DocsExtensionCopy Anchor Link

Adds any OpenAPI x- extension to the operation. The key must start with x-:

@DocsExtension('x-internal-owner', 'team-flights')

The reference doesn't display unknown extensions. They stay in the spec for your own tools and for orbitdocs lint.

Order of decoratorsCopy Anchor Link

Decorators that write the same extension don't merge. The one closest to the method wins. This affects:

• @DocsOperation and @DocsHidden (both write x-orbitdocs).
• Two @DocsContent or two @DocsSamples on one method.

@DocsErrors and Swagger's response decorators merge normally.

Next stepsCopy Anchor Link