Wie generierst du API-Dokumentation mit Swagger?

Question

Accepted Answer

NestJS integriert sich mit **Swagger/OpenAPI** über `@nestjs/swagger` um **automatisch interaktive API-Dokumentation** aus deinem Code zu generieren — Controller, Routes, DTOs und Decorators. Es erzeugt eine navigierbare UI, in der Entwickler Endpoints erforschen und testen können, die mit dem Code synchronisiert bleibt.

## Swagger einrichten

```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
```

Mit wenigen Zeilen scannt Swagger deine App und stellt interaktive Docs unter `/api/docs` bereit — automatisch reflektiert deine Routes, Parameter und DTOs.

## DTOs und Responses dokumentieren

```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 fügen Beschreibungen, Beispiele und Einschränkungen zu DTO-Feldern hinzu und bereichern das generierte Schema. (Vieles wird automatisch aus TypeScript-Typen und `class-validator` Decorators hergeleitet — das `CLI plugin` kann sogar diesen Boilerplate reduzieren.)

## Endpoints dokumentieren

```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 wie `@ApiTags`, `@ApiOperation` und `@ApiResponse` fügen Beschreibungen hinzu, gruppieren Endpoints und dokumentieren mögliche Responses.

## Was du bekommst

```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
```

## Warum es wichtig ist

API-Dokumentation ist essentiell für jede API, die von anderen genutzt wird — Frontend-Teams, mobile Apps, Drittanbieter-Integratoren oder sogar dein zukünftiges Selbst — und NestJS's Swagger-Integration macht es bemerkenswert einfach und zuverlässig, hochwertige Docs zu produzieren.

Der entscheidende Vorteil ist, dass Dokumentation **automatisch aus dem Code generiert wird** (Controller, Routes, DTOs und Decorators), sodass sie **synchronisiert bleibt** mit der tatsächlichen Implementierung, anstatt aus dem Tritt zu geraten wie handgeschriebene Docs unvermeidlich tun.

Es lohnt sich, das zu verstehen, weil gute API-Docs die Developer Experience dramatisch verbessern und Integrationsfriktion reduzieren: Die interaktive **Swagger UI** lässt Konsumenten Endpoints direkt im Browser erforschen und *testen*, und die generierte **OpenAPI-Spezifikation** kann Client-SDK-Generierung und Contract Testing vorantreiben.

Zu wissen, wie man Swagger einrichtet, die Docs mit Decorators bereichert (`@ApiProperty`, `@ApiTags`, `@ApiOperation`, `@ApiResponse`) und Authentifizierung dokumentiert, ist praktisches, häufig benötigtes Wissen — gut dokumentierte APIs sind ein professioneller Standard und ein Zeichen von Qualität in der Backend-Arbeit.

Da NestJS seine Decorator/DTO-Struktur nutzt, um so vieles automatisch zu generieren (mit minimalem zusätzlichem Aufwand), gibt es wenig Ausreden, keine exzellenten Docs zu haben, was dies zu einer wichtigen, hochgewinnbringenden Fähigkeit in echten NestJS-Projekten macht.