Meer dan alleen een
Swagger-doc.

nestjs-docfy scheidt Swagger/OpenAPI-documentatie van controllerlogica via een companion-bestandsconventie, op dezelfde manier waarop Nest dat al doet met *.controller.spec.ts.

Aan de slag Bekijk op GitHub Bekijk op npm

Installation

npm install nestjs-docfy
# peer deps
npm install @nestjs/common @nestjs/swagger reflect-metadata

Laatste release v0.13.0Licentie MIT

Companion-bestand door conventie

users.controller.ts → users.controller.docs.ts. Hetzelfde patroon dat Nest al gebruikt voor *.controller.spec.ts.

CLI met CI-gates

check, coverage --min, lint en patch-spec. Laat de build falen wanneer documentatie ontbreekt.

Automatische type-inferentie

Interfaces, class-validator en @HttpCode() worden een OpenAPI-schema zonder extra decorators.

Docfy UI AI-first

Een referentie-UI met op elk endpoint een Copy for AI-knop, ideaal om in LLM's te plakken.

docfy-ui: een AI-first referentieviewer

De OpenAPI-spec die nestjs-docfy opbouwt is ook wat docfy-ui rendert, zonder aparte configuratie en met dezelfde single source of truth.

Copy for AI: een deterministische, LLM-klare samenvatting van het endpoint, geen ruwe JSON-dump met $ref
⌘K-zoeken door elk endpoint, direct
Volledig request-/responsedetail per endpoint, rechtstreeks uit de spec gegenereerd

docfy-ui detalhe de endpoint com Copy for AI

Hoe het er in de praktijk uitziet

Voor: een controller bedolven onder decorators. Na: alleen routes, met de documentatie ernaast, in een companion-bestand.

users.controller.ts

@WithDocs()
@Controller('users')
export class UsersController {
  constructor(private readonly users: UsersService) {}

  @Get(':id')
  findOne(@Param('id') id: string) {
    return this.users.findOne(id);
  }
}

users.controller.docs.ts

import { docs } from 'nestjs-docfy';
import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger';
import { UsersController } from './users.controller';

docs(UsersController, {
  classDecorators: [ApiTags('users')],
  methods: {
    findOne: [
      ApiOperation({ summary: 'Get user by id' }),
      ApiResponse({ status: 200, description: 'OK', type: UserDto }),
      ApiResponse({ status: 404, description: 'User not found' }),
    ],
  },
});

Alleen bij het opstarten, nul overhead per requestDezelfde OpenAPI-output als inline decoratorsCompanion-bestandsconventie, zoals *.spec.ts

Geen monkey-patching, geen runtime proxies

Gewoon de juiste timing en Reflect-metadata.

Schrijf het companion-bestand

users.controller.docs.ts roept docs(UsersController, { ... }) aan, gewone Swagger-decorators, alleen in een ander bestand.

Ontdekt bij het opstarten

DocfyModule.forRoot() vindt het via naamgevingsconventie en schrijft Reflect-metadata op de methoden van de controller, vóórdat SwaggerModule.createDocument() draait.

Identieke OpenAPI-output

SwaggerModule ziet exact dezelfde metadata die het zou zien als de decorators inline op de controller stonden.

Meer dan alleen eenSwagger-doc.