Hoe genereer je API-documentatie met Swagger?

Question

Accepted Answer

NestJS integreert met **Swagger/OpenAPI** via `@nestjs/swagger` om **automatisch interactieve API-documentatie** uit je code te genereren — controllers, routes, DTOs en decorators. Dit produceert een doorbladerbare UI waar developers endpoints kunnen verkennen en testen, die gesynchroniseerd blijft met de code.

## Swagger instellen

```ts
// main.ts
import { SwaggerModule, DocumentBuilder } from "@nestjs/swagger";

const config = new DocumentBuilder()
  .setTitle("Users API")
  .setDescription("The users API documentation")
  .setVersion("1.0")
  .addBearerAuth()                       // document JWT auth
  .build();

const document = SwaggerModule.createDocument(app, config);
SwaggerModule.setup("api/docs", app, document);   // serve the UI at /api/docs
```

Met slechts enkele regels scant Swagger je app en serveert interactieve docs op `/api/docs` — automatisch je routes, parameters en DTOs weergeven.

## DTOs en responses documenteren

```ts
export class CreateUserDto {
  @ApiProperty({ example: "ann@example.com", description: "User email" })
  email: string;

@ApiProperty({ minLength: 8 })
  password: string;

@ApiPropertyOptional()                 // optional field in the docs
  age?: number;
}
```

`@ApiProperty` decorators voegen beschrijvingen, voorbeelden en beperkingen toe aan DTO-velden, waardoor het gegenereerde schema wordt verrijkt. (Veel wordt automatisch afgeleid van TypeScript-types en `class-validator` decorators — de `CLI plugin` kan zelfs deze boilerplate verder reduceren.)

## Endpoints documenteren

```ts
@ApiTags("users")                        // group endpoints in the UI
@Controller("users")
export class UsersController {
  @Post()
  @ApiOperation({ summary: "Create a user" })
  @ApiResponse({ status: 201, description: "User created", type: User })
  @ApiResponse({ status: 400, description: "Invalid input" })
  create(@Body() dto: CreateUserDto) {}
}
```

Decorators zoals `@ApiTags`, `@ApiOperation` en `@ApiResponse` voegen beschrijvingen toe, groeperen endpoints en documenteren mogelijke responses.

## Wat je krijgt

```text
✓ Interactive UI (Swagger UI) — browse, read, and TEST endpoints in the browser
✓ Auto-generated, always in sync with the code (no separate doc to maintain)
✓ The OpenAPI spec (JSON) — usable to generate client SDKs, for contract testing, etc.
✓ Request/response schemas, validation rules, auth requirements all documented
```

## Waarom het belangrijk is

API-documentatie is essentieel voor elke API die door anderen wordt gebruikt — frontend teams, mobiele apps, integrators van derden, of jezelf in de toekomst — en NestJS's Swagger-integratie maakt het produceren van hoogwaardige docs opmerkelijk gemakkelijk en betrouwbaar.

Het belangrijkste voordeel is dat documentatie **automatisch wordt gegenereerd uit de code** (controllers, routes, DTOs en decorators), dus het blijft **synchroon** met de werkelijke implementatie in plaats van verouderd te raken zoals handgeschreven documentatie onvermijdelijk doet.
/* Het begrijpen ervan is waardevol omdat goede API-docs de developer experience aanzienlijk verbeteren en integratiewrijving verminderen: de interactieve **Swagger UI** stelt consumenten in staat om endpoints rechtstreeks in de browser te verkennen en *testen*, en de gegenereerde **OpenAPI spec** kan client SDK-generatie en contract testing aandrijven.

Weten hoe je Swagger instelt, de docs verrijkt met decorators (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) en authenticatie documenteert, is praktische, regelmatig benodigde kennis — goed gedocumenteerde APIs zijn een professionele standaard en een teken van kwaliteit back-end werk.

Omdat NestJS zijn decorator/DTO-structuur gebruikt om zoveel automatisch te genereren (met minimale extra inspanning), is er weinig reden om niet over uitstekende docs te beschikken, waardoor dit een belangrijk, waardevolle mogelijkheid in echte NestJS-projecten is.